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 the 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.

Vendor bill currency	Valid payment process date	Why this matters?
`USD`	The payment `processDate` can be any US business day in the future.	The vendor pays for the exchange rate when BILL processes the payment on the `processDate`. BILL informs the vendor about the exchange rate when the payment is processed.
International currency (such as `EUR`)	The payment `processDate` must be the next US business day.	The payer pays for the exchange rate when BILL processes the payment on the `processDate`. You can get the current BILL exchange rate information with `GET /v3/payments/exchange-rate` or `POST /v3/payments/exchange-rate`

Vendor bill currency

Valid payment process date

Why this matters?

USD

The payment processDate can be any US business day in the future.

The vendor pays for the exchange rate when BILL processes the payment on the processDate. BILL informs the vendor about the exchange rate when the payment is processed.

International currency (such as EUR)

The payment processDate must be the next US business day.

The payer pays for the exchange rate when BILL processes the payment on the processDate.

You can get the current BILL exchange rate information with GET /v3/payments/exchange-rate or POST /v3/payments/exchange-rate

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 --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.

{
    "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 --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.

{
    "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 create up to 50 payments 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 --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.

{
  "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.
`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`.
`fundingAccount`	Funding account information
`amount`	Payment amount information. For a payment in an international currency (not USD), this value is in the local currency.
`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. 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 --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.

{
    "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 create up to 50 payments 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.

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.

[
    {
        "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."
    }
]

What is vendor bill currency and payment process date?

Get BILL exchange rate

Sample request

Response

Use POST /v3/payments/exchange-rate to get the current BILL exchange rates for multiple international vendors

Case 01: When the international vendor bill currency is USD

Create a payment

Sample request

Response

REMEMBER: The international vendor receives funds in their international currency

Create a bulk payment

Get BILL exchange rates for multiple vendors

Sample request

Response

Case 02: When the international vendor bill currency is not USD

The exchange rate is locked in with the batch ID

Create a payment

Sample request

Response

Create a bulk payment

Sample request

Create a bulk payment to multiple international vendors

Handle exchange rate batch ID expired error

Use `POST /v3/payments/exchange-rate` to get the current BILL exchange rates for multiple international vendors