Sign in

v1

latestOpenAPI 3.0.12026-07-24310590875.6 KB
payments

Create a payment

Create a payment.

See Get list of vendor payment options to get details about vendor payment options and payment process dates.

Note: Creating a payment requires an MFA-trusted API session. See MFA setup for information about the BILL MFA process.

See Payments in the Guides section for more information, sample requests, and responses.

post/v3/payments

Headers

sessionIdstring nullable

API session ID generated with /v3/login

Example:{{session_id}}
devKeystring nullable

Developer key generated with your BILL developer account

Example:{{developer_key}}

Request body

vendorIdstring

BILL-generated ID of the vendor to be paid. The value begins with 009.

  • If vendorId is set, it must match your bill’s vendor ID.
  • If vendorId is not set, the bill’s vendorId is automatically set.
billIdstring

BILL-generated ID of the bill to be paid. The value begins with 00n. If createBill is true, do not set billId in your payment request.

descriptionstring

Bill payment description. This value is included in the check memo or in the bank descriptor for electronic payments.

processDatestring date

Payment process date in the yyyy-MM-dd format. On this date, BILL starts processing the payment and starts withdrawing funds from the sender's funding account.

If the funding account type is set as WALLET or AP_CARD, processDate is required. For other funding account types, if processDate is not set, the date is automatically set as the next US business day.

Note: When you add a vendor bank account in the production environment, BILL requires 2 business days to complete a one-time verification of the bank account. To pay such a vendor, you must set a processDate that is 2 business days from the current date.

exchangeRateBatchIdinteger

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.

amountnumber required

Payment amount. For a payment in an international currency (not USD), this value is in the local currency.

Note: You cannot overpay a bill.

transactionNumberstring

Payment transaction reference used as an external identifier.

You can set this field as a unique alphanumeric value for your system to track the payment transaction. The value must be 50 characters or fewer. If you do not set transactionNumber, BILL sets this field as a unique alphanumeric payment identification value.

cardFundingPurposestring

Card funding purpose. This field is required for the CARD_ACCOUNT funding account type if BILL cannot identify the vendor industry.

See Get card funding purpose for more information.

Example request

{
  "vendorId": "{{vendor_id}}",
  "billId": "{{bill_id}}",
  "processDate": "2026-12-31",
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "{{org_bank_account_id}}"
  },
  "amount": 228.99,
  "processingOptions": {
    "requestPayFaster": false,
    "createBill": false
  }
}

Response

Create a payment response

idstring

BILL-generated ID of the payment. The value begins with stp.

vendorIdstring

BILL-generated ID of the vendor to be paid. The value begins with 009.

vendorNamestring

Vendor name

billIdstring

BILL-generated ID of the bill to be paid. The value begins with 00n.

descriptionstring

Bill payment description. This value is included in the check memo or in the bank descriptor for electronic payments.

processDatestring date

Payment process date in the yyyy-MM-dd format. On this date, BILL starts processing the payment and starts withdrawing funds from the sender's funding account.

amountnumber required

Payment amount. For a payment in an international currency (not USD), this value is in the local currency.

transactionNumberstring

Payment transaction reference used as an external identifier.

You can set this field as a unique alphanumeric value for your system to track the payment transaction. The value must be 50 characters or fewer. If you do not set transactionNumber, BILL sets this field as a unique alphanumeric payment identification value.

confirmationNumberstring

BILL-generated bill payment confirmation value

status'APPROVING' | 'SCHEDULED' | 'PAID' | 'CANCELLED' | 'VOID' | 'ESCHEATED' | 'UNDEFINED'

Payment status.

exchangeRatenumber

Exchange rate for the payment in an international currency (not USD)

fundingAmountnumber

Payment amount in USD

onlinePaymentboolean

Payment source.

  • true: Payment is made with BILL (online)
  • false: Payment is made outside BILL and then recorded in BILL (offline)
disbursementType'CHECK' | 'ACH' | 'RPPS' | 'PAYPAL' | 'OFFLINE' | 'INTERNATIONAL_E_PAYMENT' | 'AMEX' | 'VIRTUAL_CARD' | 'WALLET' | 'CREDIT_CARD' | 'UNDEFINED'

Disbursement type. This value is set when you create a payment. See disbursementInfo for information about the disbursement method used when BILL processes your payment.

remittanceEmailstring

Remittance email address set for the vendor

createdTimestring date-time

Payment created date and time

updatedTimestring date-time

Payment updated date and time

createdBystring

BILL-generated ID of the user that created the payment. The value begins with 006.

disbursementStatus'SCHEDULE' | 'DONE' | 'FAILED' | 'VOID' | 'HOLD' | 'FXHOLD' | 'ESCHEATED' | 'UNDEFINED'

Payment disbursement status

cardFundingPurposestring

Card funding purpose

cancelRequestSubmittedboolean

This field is set as true if a cancel payment request is submitted.

Note: If the payment is cancelled, the payment status is set as CANCELLED.

singleStatus'DISBURSEMENT_FAILED_ACTION_NEEDED' | 'DISBURSEMENT_FAILED_VENDOR_BANK_REJECTED' | 'FUNDING_FAILED_ACTION_NEEDED' | 'EXPIRING' | 'FUNDS_ESCHEATED' | 'CANCELED' | 'FUNDING_FAILED_VOIDED' | 'VOIDED' | 'CLEARED' | 'DELIVERED' | 'DISBURSEMENT_ON_HOLD' | 'VOID_PENDING' | 'SENT' | 'DISBURSEMENT_ON_HOLD_PAYER_IN_REVIEW' | 'PROCESSED' | 'FUNDING_STARTED' | 'FUNDING_ON_HOLD' | 'WAITING_ON_APPROVAL' | 'SCHEDULED' | 'READY_TO_FUND' | 'CANCELLATION_IN_PROGRESS' | 'UNDEFINED' | 'PARTIALLY_CLAIMED' | 'PAID_OFFLINE'

Unified payment status. This field provides BILL payment lifecycle updates based on the status and disbursementStatus values in the response.

See Single status payment values in the Guides section for the list of available values.