International payments

In addition to paying US vendors, you can pay international (outside US) vendors with POST /v3/payments or POST /v3/payments/bulk. To pay an international vendor (outside US) with the API, the BILL exchange rate batch ID is the additional information required at the time of creating the API request.

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.

Get BILL exchange rate batch ID

To pay an international vendor, you first get the BILL exchange rate and exchange rate batch ID with GET /v3/payments/exchange-rate.

Sample request

In this cURL example, a GET request is created for the provided international vendorId and payment amount. The amount value is the in the vendor bill currency. For example, if the vendor bill currency is EUR, the amount value in the GET request is 1000 EUR.

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 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 an additional required field for paying the international vendor with POST/v3/payments.

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.

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

Pay an international vendor

In your POST /v3/payments request, set the required fields.

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 1000 EUR 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 exchangeRateBatchId is set as a required field for paying the international vendor.

Funding account details are added to provide a bank account source for the payment. You can retrieve the bank account id with GET /v3/bankaccounts. 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,
  "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 disbursed from your 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 bulk payment to an international vendor

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.

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 exchangeRateBatchId is set as a required field for paying the international vendor.

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 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. In your POST /v3/payments/exchange-rate request, set the required fields.

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. For example, if the vendor bill currency is CAD, the amount value in the POST request is 150 CAD.

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 0.8361528 tells us that 1 USD = 0.8361528 EUR The exchangeRateBatchId value is an additional required field for paying the international vendor with POST/v3/payments.

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": "CAD",
      "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": "GBP",
      "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": "GBP",
      "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 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 current 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."
    }
]