International AP payments workflow
The BILL v3 API gives you access to the same infrastructure that powers the BILL Accounts Payable (AP), Accounts Receivable (AR), and Spend & Expense (S&E) products. In addition, you can receive real-time event notifications with webhooks.
In this recipe
In this recipe, you learn how to send AP payments to international vendors with the API.
AP payments is the final and most crucial step of the AP workflow. With AP payments, you settle vendor debts and unpaid vendor bills. Whether you are paying a single vendor or clearing dozens of bills at once, the BILL v3 API enables you to securely handle payments at scale.
What you'll build
In this recipe, you create an integration with the BILL API in the sandbox environment.
- Pay an international (outside US) vendor when the vendor bill currency is USD. You get the current BILL exchange rate information, and then clear unpaid vendor bills.
- Pay an international vendor when the vendor bill currency is not USD. You get the required exchange rate batch ID, and then clear unpaid vendor bills.
What you need before you begin
| Prerequisite | Description |
|---|---|
| API basics | A basic understanding of working with API endpoints. |
| Credentials | Your credentials are required for you to build with the BILL AP & AR API. If you have not set up your credentials, sign up to create your sandbox BILL account. When you sign up, you create a test BILL organization, and you generate your username, password, organization ID, and developer key. See Sandbox API sign up for detailed steps. |
| MFA setup | Your MFA setup must be complete. BILL requires MFA for creating payments with the API. MFA at BILL requires a one-time setup. When you sign up with the BILL web app to generate your credentials, you complete 2-step verification/MFA with a valid phone number. |
| Test bank account | A test bank account added in your BILL organization. You use this test bank account to create a test payment in this recipe. See Sandbox API bank account setup for detailed steps. |
Chapter 1: API login
In this chapter, you login to your BILL account with the API.
To begin, enter your API login credentials in the fields below. See the What you need before you begin section in this recipe if you have not set up your credentials.
https://gateway.stage.bill.com/connecthttps://gateway.prod.bill.com/connectComplete your API login with the required credentials. Simply click Send to get a 200 OK response.
In the response, a new sessionId is available. You use this sessionId and your devKey in all subsequent BILL API requests. A 200 OK response confirms that you are a signed-in user. The sessionId expires after 35 minutes of inactivity. At that point, you are automatically signed out, and you must sign in again with the API login endpoint and generate a new sessionId.
Note that the trusted field in the response is set as false. When the API login session is MFA-trusted, the trusted field is set as true. We enable MFA in this API session in Chapter 2.
Chapter 2: MFA
In this chapter, you step up your current API session as MFA-trusted. BILL requires MFA for creating payments with the API. In the next set of steps, you first generate an MFA challenge, validate the MFA challenge, and then step-up the API login session as MFA-trusted.
Step 1: Generate MFA challenge
Generate an MFA challenge ID with POST /v3/mfa/challenge. Click Send. You receive a 6-digit token sent to your phone number.
In the response, a challengeId is available. You use this value in Step 2.
Step 2: Validate MFA challenge
Validate the MFA challenge with POST /v3/mfa/challenge/validate. In the request, set the required fields, and then click Send.
- Set
tokenas the 6-digit token sent to your phone number. - Set
deviceandmachineNameas a test device name. For example,test-device. Device name is required in the next step.
In the response, a rememberMeId is available. You use this value in Step 3.
Step 3: Step-up API session as MFA-trusted
Step-up your API session as MFA-trusted with POST /v3/mfa/step-up. In the request, set device as the device name used in Step 2, and then click Send. Your current API session is now MFA-trusted.
In the response, trusted is set as true. Your API session is now MFA-trusted.
Chapter 3: When the vendor bill currency is USD
In this chapter, you pay an international vendor with bill currency set as USD. Use POST /v3/payments to pay an international vendor. Use POST /v3/payments/bulk to pay multiple bills and multiple vendors with one API request.
Before you begin, it is important to learn about vendor billCurrency and how it relates to payment processDate.
| Concept | Description |
|---|---|
| Vendor bill currency | The international vendor billCurrency defines the currency that BILL uses to create bills for the vendor. For example, an international vendor in France may have billCurrency set as USD or EUR. |
| Payment process date | The payment processDate is the date when BILL starts processing a payment and starts withdrawing funds from the sender's funding account.
|
In the next set of steps, you first create an international vendor record with bill currency set as USD. You then create a bill for the international vendor, and get the current BILL exchange rate. Finally, you pay the bill with the API.
In this chapter, you create a payment for just one bill. Like with creating a payment, you can create a bulk payment to an international vendor.
You first get the current BILL exchange rate and exchange rate batch ID with GET /v3/payments/exchange-rate (or with POST /v3/payments/exchange-rate for multiple vendors with one API request) and then continue with your bulk payment to international vendors with POST /v3/payments/bulk. You can pay up to 50 bills with one POST /v3/payments/bulk request.
Step 1: Create an international vendor record with bill currency set as USD
When you create a vendor with POST /v3/vendors, you add a new international vendor record in your BILL organization.
Click Body below to view an example body for the Create a vendor API request. In the request, the test international vendor is set in France, and billCurrency is set as USD. Click Send to create a new international vendor record with an address in France.
In the response, a BILL-generated vendor id is available. You can sign in to the BILL web app to view this international vendor record in your BILL organization. In Step 2, you use this vendor id to create a bill for the international vendor.
Step 2: Create a bill for the international vendor
When you create a bill with POST /v3/bills, you create a new bill record for the test international vendor from Step 1.
Click Body below to view an example body for the Create a bill API request. In the request, the bill amount values are in USD since the vendor billCurrency is USD. Click Send to create a new bill for the international vendor.
In the response, a BILL-generated bill id is available. You can sign in to the BILL web app to view this bill in your BILL organization. Since the vendor billCurrency is USD, the bill currency is USD.
Step 3: Get the current BILL exchange rate
To pay international vendors, you first get the current BILL exchange rate information. You can display this BILL exchange rate information for the payer before they create an international payment.
Click Send to get the current BILL exchange rate with GET /v3/payments/exchange-rate. In the request, vendorId is set as the international vendor id from Step 1, and amount is set as the total bill amount from Step 2.
In the response, the BILL exchangeRate and exchangeRateBatchId is available. In addition, billCurrency states the vendor bill currency, paymentCurrency states the currency in which the vendor accepts payments, and baseCurrency states the base currency used for BILL exchange rate calculation.
Step 4: Get details about your test bank account
BILL requires information about your BILL organization bank account before you can create a payment. Click Send to get the list of test bank accounts in your BILL organization with GET /v3/funding-accounts/banks.
In the request, you add a filters query parameter to get a verified test bank account ("status": "VERIFIED"). If you do not have a test bank account in your sandbox BILL account, see Sandbox API bank account setup for detailed steps.
In the response, you get the test bank account id for each test bank account in your BILL organization. In Step 5, you use the id of a verified test bank account ("status": "VERIFIED").
Step 5: Pay the international vendor
When you create a payment with POST /v3/payments, a payment record is created in your BILL organization.
Click Body below to view an example body for the Create a payment API request. In the request, the funding account id is set as the id of a verified test bank account (from Step 4), and amount is set as the bill amount (from Step 2). Since the vendor billCurrency is USD, processDate can be any US business day in the future.
Click Send to create a new payment.
You just created a test payment to an international test vendor. In the response, a BILL-generated payment id is available for the paid bill. Since the vendor billCurrency is USD, the payment amount value is in USD.
You can sign in to the BILL web app to view this payment in your BILL organization. An email is also sent to your email address about the scheduled payment to the test vendor.
Chapter 4: When the vendor bill currency is not USD
In this chapter, you pay an international vendor with bill currency set as EUR (not USD). Use POST /v3/payments to pay an international vendor. Use POST /v3/payments/bulk to pay multiple bills and multiple vendors with one API request.
When the vendor billCurrency is not USD, there are a set of additional rules for creating a payment.
- Payment process date: When the vendor
billCurrencyis notUSD, the paymentprocessDatemust be the next US business day. - Exchange rate batch ID: The current BILL exchange rate batch ID is required for creating an international payment with the API. You can get this information with
GET /v3/payments/exchange-rateorPOST /v3/payments/exchange-rate.
In the next set of steps, you first create an international vendor record with bill currency set as EUR. You then create a bill for the international vendor, and get the current BILL exchange rate batch ID. Finally, you pay the bill with the API.
In this chapter, you create a payment for just one bill. Like with creating a payment, you can create a bulk payment to an international vendor.
You first get the current BILL exchange rate and exchange rate batch ID with GET /v3/payments/exchange-rate (or with POST /v3/payments/exchange-rate for multiple vendors with one API request) and then continue with your bulk payment to international vendors with POST /v3/payments/bulk. You can pay up to 50 bills with one POST /v3/payments/bulk request.
Step 1: Create an international vendor record with bill currency set as EUR
When you create a vendor with POST /v3/vendors, you add a new international vendor record in your BILL organization.
Click Body below to view an example body for the Create a vendor API request. In the request, the test international vendor is set in France, and billCurrency is set as EUR. Click Send to create a new international vendor record with an address in France.
In the response, a BILL-generated vendor id is available. You can sign in to the BILL web app to view this international vendor record in your BILL organization. In Step 2, you use this vendor id to create a bill for the international vendor.
Step 2: Create a bill for the international vendor
When you create a bill with POST /v3/bills, you create a new bill record for the test international vendor from Step 1.
Click Body below to view an example body for the Create a bill API request. In the request, the bill amount values are in EUR since the vendor billCurrency is EUR. Click Send to create a new bill for the international vendor.
In the response, a BILL-generated bill id is available. Since the vendor billCurrency is EUR, the bill currency is EUR, the amount value is in EUR, and the fundingAmount value is in USD.
Step 3: Get the current BILL exchange rate batch ID
The current BILL exchange rate batch ID is required at the time of creating a payment for an international vendor when the vendor bill currency is not USD. BILL maintains all exchangeRate values in a batch. When a batch expires, a new batch ID is generated and all exchangeRate values are updated in the new batch.
In the request, amount is set as the amount in EUR for the bill created in Step 2. Click Send to get the current BILL exchange rate and exchange rate batch ID with GET /v3/payments/exchange-rate.
In the response, the BILL exchangeRate and exchangeRateBatchId is available. In addition, billCurrency states the vendor bill currency, paymentCurrency states the currency in which the vendor accepts payments, and baseCurrency states the base currency used for BILL exchange rate calculation.
In Step 4, you use the exchangeRateBatchId in the POST /v3/payments API request. The payment processDate must be the next US business day when the vendor billCurrency is not USD.
Step 4: Pay the international vendor
When you create a payment with POST /v3/payments, a payment record is created in your BILL organization.
Click Body below to view an example body for the Create a payment API request. In the request, the funding account id is set as the id of a verified test bank account, and amount is set as the bill amount (from Step 2). Since the vendor billCurrency is EUR, processDate must be the next US business day, and exchangeRateBatchId is required. You get this information from Step 3.
Click Send to create a new payment.
You just created a test payment. In the response, a BILL-generated payment id is available for the paid bill. Since the vendor billCurrency is EUR, the payment amount value is in EUR.
You can sign in to the BILL web app to view this payment in your BILL organization. An email is also sent to your email address about the scheduled payment to the test vendor.
What you learned in this recipe
You just completed international AP payments with the BILL v3 API. You learned a lot along the way.
- Create an API session and perform MFA step-up.
- Create test international vendor records with vendor bill currency set as USD and EUR.
- Create test bills for international vendors.
- Pay bills with the API.
- Pay an international vendor when vendor bill currency is USD.
- Pay an international vendor when vendor bill currency is EUR (not USD).
Updated 4 days ago