API Reference
System Status

Create a payment

post
https://gateway.stage.bill.com/connect/v3/payments

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.

Body Params
string

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

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.

string
length ≤ 70

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

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.

int32

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
object
required

Payment funding information (Bank account, card account, or wallet)

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

processingOptions
object
required

Payment processing options

paymentPurpose
object

Payment purpose information for compliance with international payment rules of the vendor country. This one-time configuration is required for enabling electronic payments to international vendors.

You can set paymentPurpose at the time of creating a vendor, updating vendor details, or creating a payment. To set paymentPurpose at the time of creating a payment, use the information from GET /v3/vendors/{vendorId}/configuration.

Note: Set paymentPurpose only when it is required. Vendor countries, like Japan, do not require any payment purpose information. For such countries, setting paymentPurpose in your request results in an error response.

See Create an international vendor for more information on how to set paymentPurpose.

string
length ≤ 50

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.

string

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.

vendorCredits
array of objects

Vendor credits applied to the bill payment. To edit the vendor credit amount applied to the bill, set the same vendor credit id in your payment request. To apply an additional vendor credit to the bill, set the new vendor credit id in your payment request.

vendorCredits
Headers
string | null

API session ID generated with /v3/login

string | null

Developer key generated with your BILL developer account

Responses

Updated 15 days ago

Language
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated 15 days ago