--- updatedAt: 2026-06-10T20:44:53.000Z agentTools: projectIndex: https://developer.bill.com/llms.txt --- # International payments You can pay both US vendors and international (outside US) vendors with `POST /v3/payments` or `POST /v3/payments/bulk`. When you pay international vendors, the vendors receive funds in their international currency. For example, an international vendor in France receives funds in `EUR`. See the /v3/payments API for the complete list of available operations. ## What is vendor bill currency and payment process date? Before you create an international payment with the API, it is important for us to learn about vendor `billCurrency` and how it relates to payment `processDate`. 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`. You get this information with `GET /v3/vendors` or `GET /v3/vendors/{vendorId}`. The vendor `billCurrency` affects the available payment `processDate` for international payments. The payment `processDate` is the date when BILL starts processing a payment and starts withdrawing funds from the sender's funding account.
Bill currency Payment currency Foreign exchange details Process date Payment delivery method
`USD` `USD` No conversion Any US business day in the future Wire transfer
`USD` International currency (such as `EUR`) Vendor pays for exchange rate when BILL processes the payment. BILL informs the vendor about the exchange rate when the payment is processed. Any US business day in the future Local transfer or Wire transfer
International currency (such as `EUR`) International currency (such as `EUR`) Payer pays for exchange rate when BILL processes the payment. You can get the current BILL exchange rate information with `GET /v3/payments/exchange-rate` or `POST /v3/payments/exchange-rate` **Must be** the next US business day Local transfer or Wire transfer
See the [International payments delivery methods](https://developer.bill.com/docs/ap-international-payments#international-payments-delivery-methods) section to learn about the delivery methods for BILL international payments. ## Get BILL exchange rate 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. To pay international vendors, you first get the current BILL exchange rate information with `GET /v3/payments/exchange-rate` or `POST /v3/payments/exchange-rate`. You can display the current BILL exchange rate information for the payer before they create an international payment. ### Sample request In this cURL example, a GET request is created with the provided international `vendorId` and payment `amount`. The `amount` value is in the vendor bill currency. For example, if the vendor bill currency is `USD`, the `amount` value in the GET request is `USD 1000`. If the vendor bill currency is `EUR`, the `amount` value in the GET request is `EUR 1000`. ```curl curl --request GET \ --url 'https://gateway.stage.bill.com/connect/v3/payments/exchange-rate?vendorId={vendor_id}&amount=1000' \ --header 'content-type: application/json' \ --header 'devKey: {developer_key}' \ --header 'sessionId: {session_id}' ``` ### Response In the sample response, the BILL `exchangeRate` and `exchangeRateBatchId` is available. An `exchangeRate` of `0.8361528` tells us that `1 USD = 0.8361528 EUR`. The `exchangeRateBatchId` value is required for paying international vendors with a specific configuration. You will learn more about `exchangeRateBatchId` in the later sections. 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 production, a BILL batch is valid for a maximum of 20 minutes. The `expirationTime` in the response provides the timestamp when the current batch will expire. For example, if a batch has been active for 17 minutes when you get the `exchangeRateBatchId`, `expirationTime` indicates that you have 3 minutes remaining before the batch will expire. When the batch expires, you need a new batch ID. ```json { "billCurrency": "EUR", "paymentCurrency": "EUR", "baseCurrency": "USD", "exchangeRate": 0.8361528, "exchangeRateBatchId": 35664, "vendorId": "{vendor_id}", "amountRange": { "from": 852.00, "to": 4260.00 }, "expirationTime": "2026-12-21T23:56:52.127+00:00" ``` > ๐Ÿ‘ Use **`POST /v3/payments/exchange-rate`** to get the current BILL exchange rates for multiple international vendors > > You can get the current BILL exchanges rates for multiple international vendors with a single `POST /v3/payments/exchange-rate` API request. > > This API endpoint is useful when you want to display the current exchange rate information for each vendor before a bulk payment is created for multiple international vendors (with `POST /v3/payments/bulk`). ## Case 01: When the international vendor bill currency is USD When the vendor `billCurrency` is `USD`, you simply get the current BILL exchange rate information with `GET /v3/payments/exchange-rate`, and then continue with paying the international vendor with `POST /v3/payments` or `POST /v3/payments/bulk`. ### Create a payment In your `POST /v3/payments` request, set the required fields.
Field Description
`billId` BILL-generated ID of the bill to be paid. The value begins with **`00n`**.
`processDate` Bill payment processing date in the **`yyyy-MM-dd`** format. On this date, BILL starts processing a payment and starts withdrawing funds from the sender's funding account.
`fundingAccount` Funding account information
`amount` Payment amount information. Since the vendor `billCurrency` is `USD`, the `amount` value is in `USD`.
`processingOptions` Payment processing options. * Set **`createBill`** as **`false`** to create a vendor payment for an existing bill. * Set **`createBill`** as **`true`** to create a bill for a vendor payment. If **`createBill`** is **`true`**, do not set **`billId`** in your payment request.
See the POST /v3/payments API for more information about the other payment fields you can set. #### Sample request In this cURL example, an international payment of `USD 1000` is created for the vendor (`vendorId`). The `billId` is associated with the payment to link the payment with the bill line items and amount. Funding account details are added to provide a bank account source for the payment. You can retrieve the bank account `id` with `GET /v3/funding-accounts/banks`. See Get list of bank accounts in the API reference for more information. ```curl curl --request POST \ --url 'https://gateway.stage.bill.com/connect/v3/payments' \ --header 'content-type: application/json' \ --header 'devKey: {developer_key}' \ --header 'sessionId: {session_id}' \ --data '{ "vendorId": "{vendor_id}", "billId": "{bill_id}", "processDate": "2026-12-21", "fundingAccount": { "type": "BANK_ACCOUNT", "id": "{org_bank_account_id}" }, "amount": 1000.00, "processingOptions": { "requestPayFaster": false, "createBill": false } }' ``` #### Response In the response, a BILL-generated payment `id` is available. The value begins with `stp`. The `amount` value is in `USD`. In addition, disbursement information is available based on the type of payment. The `singleStatus` field provides a complete view of your payment based on `status` and `disbursementStatus` at different stages of your payment lifecycle. See Single status payment values for more information. > ๐Ÿ‘ REMEMBER: The international vendor receives funds in their international currency > > When you pay international vendors, the vendors receive funds in their international currency. For example, an international vendor in France receives funds in `EUR`. ```json { "id": "{sent_payment_id}", "vendorId": "{vendor_id}", "billId": "{bill_id}", "billPayments": [ { "id": "{bill_payment_id}", "billId": "{bill_id}", "amount": 1000.00 } ], "description": "Inv #202601", "processDate": "2026-12-21", "fundingAccount": { "type": "BANK_ACCOUNT", "id": "{org_bank_account_id}" }, "amount": 1000.00, "processingOptions": { "requestPayFaster": false, "createBill": false, "requestCheckDeliveryType": "STANDARD" }, "transactionNumber": "PLBAOBWYTOZRZJKHPPCV", "confirmationNumber": "P26012602 - 2396379", "status": "SCHEDULED", "onlinePayment": true, "disbursementType": "INTERNATIONAL_E_PAYMENT", "createdTime": "2026-12-21T21:42:23.394+00:00", "updatedTime": "2026-12-21T21:42:23.000+00:00", "createdBy": "{user_id}", "voidInfo": [], "cancelRequestSubmitted": false, "singleStatus": "SCHEDULED" } ``` ### Create a bulk payment Just like with creating a single payment, you first get the current BILL exchange rate information with `GET /v3/payments/exchange-rate`, and then continue with your bulk payment to the international vendor with `POST /v3/payments/bulk`. You can pay up to 50 bills with one `POST /v3/payments/bulk` request. The API request and response structures match the US vendor examples. See Create a bulk payment in the **Payments** Guides section for more information. #### Get BILL exchange rates for multiple vendors When you want to create a bulk payment to multiple vendors with one `POST /v3/payments/bulk` API request, you first get the current BILL exchange rate information for the complete list of vendors with one `POST /v3/payments/exchange-rate` API request. In your `POST /v3/payments/exchange-rate` request, set the required fields. | Field | Description | | :--------- | :----------------------------------------------------------------------------------------- | | `vendorId` | BILL-generated ID of the international vendor to be paid. The value begins with **`009`**. | | `amount` | Payment amount. The amount is in the vendor bill currency. | #### Sample request In this cURL example, a POST request is created for a set of vendor ID and payment `amount` values. For each vendor payment, the `amount` value is the in the vendor bill currency. ```curl curl --request POST \ โ€“-url 'https://gateway.stage.bill.com/connect/v3/payments/exchange-rate' \ --header 'content-type: application/json' \ --header 'devKey: {developer_key}' \ --header 'sessionId: {session_id}' \ --data '[ { "vendorId": "{vendor_id01}", "amount": 150.00 }, { "vendorId": "{vendor_id02}", "amount": 299.95 }, { "vendorId": "{vendor_id03}", "amount": 450.00 } ]' ``` #### Response In the response, the BILL `exchangeRateBatchId` and the `exchangeRate` for each international vendor is available. An `exchangeRate` of `1.36929112` tells us that `1 USD = 1.36929112 CAD`. In addition, `billCurrency` states the vendor bill currency , `paymentCurrency` states the currency in which the vendor accepts payments, and `baseCurrency` states the currency in which your organization will pay the vendor. ```json { "exchangeRateBatchId": 35664, "exchangeRatesโ€: [ { "billCurrency": "USD", "paymentCurrency": "CAD", "baseCurrency": "USD", "vendorId": "{vendor_id01}", "exchangeRate": 1.36929112, "amountRange": { "from": 0.00, "to": 1389.30 }, "expirationTime": "2026-12-21T07:34:47.000+00:00" }, { "billCurrency": "USD", "paymentCurrency": "GBP", "baseCurrency": "USD", "vendorId": "{vendor_id02}", "exchangeRate": 0.7361528, "amountRange": { "from": 0.00, "to": 995.95 }, "expirationTime": "2026-12-21T07:34:47.000+00:00" }, { "billCurrency": "USD", "paymentCurrency": "GBP", "baseCurrency": "USD", "vendorId": "{vendor_id03}", "exchangeRate": 0.7361528, "amountRange": { "from": 0.00, "to": 995.95 }, "expirationTime": "2026-12-21T07:34:47.000+00:00" } ] } ``` You can now create a bulk payment to multiple international vendors with the `POST /v3/payments/bulk` API request. The API request and response is the same as how you would pay multiple US vendors. See Create a bulk payment in the **Payments** Guides section for more information. ## Case 02: When the international vendor bill currency is not USD When the vendor `billCurrency` is in an international currency (such as `EUR`), international payments at BILL follow a set of rules. * **Payment process date**: The payment `processDate` must be the next US business day. * **Exchange rate batch ID**: The current BILL exchange rate batch ID is the additional information required at the time of creating an international payment with the API. You can get this information with `GET /v3/payments/exchange-rate` or `POST /v3/payments/exchange-rate`. > ๐Ÿ‘ The exchange rate is locked in with the batch ID > > The exchange rate is locked in for an international payment with a batch ID value. If you get an exchange rate of `1 USD = 0.8361528 EUR` in a batch, BILL will honor this exchange rate at the time of processing an international payment. ### Create a payment In your `POST /v3/payments` request, set the required fields.
Field Description
`billId` BILL-generated ID of the bill to be paid. The value begins with **`00n`**.
`processDate` Bill payment processing date in the **`yyyy-MM-dd`** format. On this date, BILL starts processing a payment and starts withdrawing funds from the sender's funding account.
`fundingAccount` Funding account information
`amount` Payment amount information. For a payment in an international currency (not USD), this value is in the local currency.
`exchangeRateBatchId` Exchange rate batch ID. This field is required for paying international vendors when the vendor bill currency is not USD. Get the current BILL exchange rate and exchange rate batch ID with **`GET /v3/payments/exchange-rate`**.
`processingOptions` Payment processing options. * Set **`createBill`** as **`false`** to create a vendor payment for an existing bill. * Set **`createBill`** as **`true`** to create a bill for a vendor payment. If **`createBill`** is **`true`**, do not set **`billId`** in your payment request.
See the POST /v3/payments API for more information about the other payment fields you can set. #### Sample request In this cURL example, a vendor payment of `EUR 1000` is created for the vendor (`vendorId`). The `billId` is associated with the payment to link the payment with the bill line items and amount. The `processDate` is set as the next US business day. Funding account details are added to provide a bank account source for the payment. You can retrieve the bank account `id` with `GET /v3/funding-accounts/banks`. See Get list of bank accounts in the API reference for more information. ```curl curl --request POST \ --url 'https://gateway.stage.bill.com/connect/v3/payments' \ --header 'content-type: application/json' \ --header 'devKey: {developer_key}' \ --header 'sessionId: {session_id}' \ --data '{ "vendorId": "{vendor_id}", "billId": "{bill_id}", "processDate": "2026-12-21", "fundingAccount": { "type": "BANK_ACCOUNT", "id": "{org_bank_account_id}" }, "amount": 1000.00, "exchangeRateBatchId": 35664, "processingOptions": { "requestPayFaster": false, "createBill": false } }' ``` #### Response In the response, a BILL-generated payment `id` is available. The value begins with `stp`. In addition, `exchangeRate` states the current BILL exchange rate for `EUR` in the payment, `amount` states the amount in `EUR`, and `fundingAmount` states the `USD` amount that will be debited from the organization bank account. The `singleStatus` field provides a complete view of your payment based on `status` and `disbursementStatus` at different stages of your payment lifecycle. See Single status payment values for more information. ```json { "id": "{sent_payment_id}", "vendorId": "{vendor_id}", "billId": "{bill_id}", "billPayments": [ { "id": "{bill_payment_id}", "billId": "{bill_id}", "amount": 1000.00 } ], "description": "Inv #202601", "processDate": "2026-12-21", "fundingAccount": { "type": "BANK_ACCOUNT", "id": "{org_bank_account_id}" }, "amount": 1000.00, "processingOptions": { "requestPayFaster": false, "createBill": false, "requestCheckDeliveryType": "STANDARD" }, "transactionNumber": "PLBAOBWYTOZRZJKHPPCV", "confirmationNumber": "P26012602 - 2396379", "status": "SCHEDULED", "exchangeRate": 0.8361528, "fundingAmount": 1195.95, "onlinePayment": true, "disbursementType": "INTERNATIONAL_E_PAYMENT", "createdTime": "2026-12-21T21:42:23.394+00:00", "updatedTime": "2026-12-21T21:42:23.000+00:00", "createdBy": "{user_id}", "voidInfo": [], "cancelRequestSubmitted": false, "singleStatus": "SCHEDULED" } ``` ### Create a bulk payment You can pay up to 50 bills with one `POST /v3/payments/bulk` request. In your `POST /v3/payments/bulk` request, set the required fields.
Field Description
`processDate` Bill payment processing date in the **`yyyy-MM-dd`** format. On this date, BILL starts processing a payment and starts withdrawing funds from the sender's funding account.
`fundingAccount` Funding account information
`exchangeRateBatchId` Exchange rate batch ID. This field is required for paying international vendors when the vendor bill currency is not USD. Get the current BILL exchange rate and exchange rate batch ID with **`GET /v3/payments/exchange-rate`**.
`billId` BILL-generated ID of the bill to be paid. This value begins with **`00n`**.
`amount` Payment amount
See the POST /v3/payments/bulk API for more information about the other payment fields you can set. #### Sample request In this cURL example, a bulk payment is created for an international vendor. Each bill ID is associated with the payment to link the payment with the bill line items and amount. The `processDate` is set as the next US business day. The `exchangeRateBatchId` is set as a required field for paying the international vendor when the vendor bill currency is not USD. Get the current BILL exchange rate and exchange rate batch ID with `GET /v3/payments/exchange-rate`. ```curl curl --request POST \ โ€“-url 'https://gateway.stage.bill.com/connect/v3/payments/bulk' \ --header 'content-type: application/json' \ --header 'devKey: {developer_key}' \ --header 'sessionId: {session_id}' \ --data '{ "processDate": "2025-12-21", "fundingAccount": { "type": "BANK_ACCOUNT", "id": "{org_bank_account_id}" }, "exchangeRateBatchId": 35664, "payments": [ { "billId": "{bill_id01}", "amount": 150.00 }, { "billId": "{bill_id02}", "amount": 299.95 }, { "billId": "{bill_id03}", "amount": 450.00 } ] }' ``` ### Create a bulk payment to multiple international vendors To pay an international vendor, you first get the BILL exchange rates for each international vendor and the associated exchange rate batch ID with `POST /v3/payments/exchange-rate`. From the response, you use the `exchangeRateBatchId` value in your `POST /v3/payments/bulk` API request. ## Handle exchange rate batch ID expired error 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. When you create a payment with an expired `exchangeRateBatchId` value, you get an HTTP 422 response with the `BDC_1436` error code. When you see this response, get the new `exchangeRateBatchId` value from `GET /v3/payments/exchange-rate` or `POST /v3/payments/exchange-rate`, and use this value in your create payment API request. ```json [ { "timestamp": "2026-12-22T19:17:00.549+00:00", "code": "BDC_1436", "severity": "ERROR", "category": "DOWNSTREAM", "message": "Exchange rate quote expired." }, { "timestamp": "2026-12-22T19:17:00.549+00:00", "code": "BDC_1436", "severity": "ERROR", "category": "DOWNSTREAM", "message": "{bill_id} : Exchange rate quote expired." } ] ``` ## International payments delivery methods For international payments, BILL uses wire transfer and local transfer as the payment delivery methods. In the vendors API response, the `payByType` (`INTERNATIONAL_E_PAYMENT`), `payBySubType`, and `transferMethod` fields provide information about the payment delivery method. When an international vendor is eligible to be paid by both Wire transfer and Local transfer, `payBySubType` is set as `MULTIPLE` and `transferMethod` is set as the default payment method (`WIRE` or `LOCAL`) set by BILL. | Feature | Wire transfer | Local transfer | | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | | Delivery method | BILL delivers wire transfers with the SWIFT network or through intermediary banks. | BILL delivers local transfers with the vendor country's domestic payment network. If available, BILL defaults to using local transfer. | | Delivery timing | Delivery timing depends on the vendor country. | Payments can be delivered up to 4 days faster than wire transfers. Most local transfers are delivered in 24 hours. | | Payment currency | Payments can be made in USD and in the international currency.

Wire transfers are available in more currencies as compared to local transfer. | Payments can be made only in the international currency. | | Availability | No specific rules on availability. | Availability depends on vendor country & payment limit threshold. | > ๐Ÿ‘ Notes about international payments delivery methods > > You can fund international payments with your bank account, credit card, or debit card. Visa, Mastercard, and Discover are the only card options available. > > The BILL Network extends to international vendors. Currently, BILL has Network support for many countries, & the list continues to grow. See Network-supported countries in the BILL Help Center for more information.