---
title: "Create a payment"
method: POST
path: "/v3/payments"
tags: ["payments"]
---

# Create a payment

`POST /v3/payments`

Create a payment.

See [Get list of vendor payment options](https://developer.bill.com/reference/listpaymentoptions) to get details about vendor payment options and payment process dates.

**Note**: Creating a payment requires an MFA-trusted API session. See [MFA setup](https://developer.bill.com/reference/setup) for information about the BILL MFA process.

See [Payments](https://developer.bill.com/docs/ap-payments) in the Guides section for more information, sample requests, and responses.

## Headers

- `sessionId` string, nullable — API session ID generated with `/v3/login`
- `devKey` string, nullable — Developer key generated with your BILL developer account

## Request body

- PaymentRequestDto — Create a payment
  - `vendorId` 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.
  - `billId` 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.
  - `description` string — Bill payment description. This value is included in the check memo or in the bank descriptor for electronic payments.
  - `processDate` string, 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.
  - `exchangeRateBatchId` integer — 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)
    - `type` 'BANK_ACCOUNT' | 'CARD_ACCOUNT' | 'WALLET' | 'AP_CARD', required — Payment funding type. * `BANK_ACCOUNT`: Bank account * `CARD_ACCOUNT`: Credit card or debit card * `WALLET`: BILL balance * `AP_CARD`: AP Card See the BILL Help FAQ sections for [BILL balance](https://help.bill.com/direct/s/article/4409933681677) and [AP Card](https://help.bill.com/direct/s/article/000003348) for more information.
    - `id` string — BILL-generated ID of the selected payment funding type. For the `WALLET` type, the `id` is not required.
  - `amount` 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
    - `requestPayFaster` boolean — Set as `true` to use BILL Pay Faster. This field is required if `requestCheckDeliveryType` is set. See [Payments](https://developer.bill.com/docs/ap-payments) in the Guides section for information about BILL Pay Faster payments.
    - `createBill` boolean — * Set as `false` to create a vendor payment for an existing bill. * Set as `true` to create a bill for a vendor payment. If `createBill` is `true`, do not set `billId` in your payment request.
    - `requestCheckDeliveryType` 'STANDARD' | 'UPS_1DAY' | 'UPS_2DAY' | 'UPS_3DAY' | 'RTP_DELIVERY' — BILL Pay Faster payment delivery type. The `RTP_DELIVERY` option is not available for vendor payments by check.
  - `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](https://developer.bill.com/docs/creating-an-international-vendor) for more information on how to set `paymentPurpose`.
    - `text` string — Payment purpose text. This can be any user-defined text. If you set `text`, do not set `code`.
    - `code` object — Payment purpose code. If you set the `code` object, do not set `text`.
      - `name` string, required — Name
  - `transactionNumber` string — 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.
  - `cardFundingPurpose` 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](https://developer.bill.com/reference/listcardfundingpurposes) for more information.
  - `vendorCredits` PaymentVendorCreditRequestDto[] — 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.
    - `id` string, required — BILL-generated ID of the vendor credit applied to the bill payment. The value begins with `vcr`.
    - `amount` number, required — Credit amount

## Response `201`

Create a payment response

- PaymentResponseDto — Payments response.
  - `id` string — BILL-generated ID of the payment. The value begins with `stp`.
  - `vendorId` string — BILL-generated ID of the vendor to be paid. The value begins with `009`.
  - `vendorName` string — Vendor name
  - `billId` string — BILL-generated ID of the bill to be paid. The value begins with `00n`.
  - `billPayments` BillPayment[] — List of bill payments. When a payment is applied to a bill, the bill payment is identified by a bill payment `id`. The value begins with `blp`.
    - `id` string — BILL-generated ID of the bill payment. The value begins with `blp`.
    - `billId` string — BILL-generated ID of the bill to be paid. The value begins with `00n`.
    - `amount` number — Payment amount. For a payment in an international currency (not USD), this value is in the local currency.
    - `vendorCredits` PaymentVendorCreditResponseDto[] — Vendor credits applied to the bill payment
      - `id` string — BILL-generated ID of the vendor credit applied to the bill payment. The value begins with `vcr`.
      - `amount` number — Credit amount
  - `description` string — Bill payment description. This value is included in the check memo or in the bank descriptor for electronic payments.
  - `processDate` string, 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.
  - `fundingAccount` object — Payment funding information
    - `type` 'BANK_ACCOUNT' | 'CARD_ACCOUNT' | 'WALLET' | 'AP_CARD' | 'UNDEFINED', required — Payment funding type. * `BANK_ACCOUNT`: Bank account * `CARD_ACCOUNT`: Credit card or debit card * `WALLET`: BILL balance * `AP_CARD`: AP Card See the BILL Help FAQ sections for [BILL balance](https://help.bill.com/direct/s/article/4409933681677) and [AP Card](https://help.bill.com/direct/s/article/000003348) for more information.
    - `id` string — BILL-generated ID of the selected payment funding type. For the `WALLET` type, the `id` is not required.
  - `amount` number, required — Payment amount. For a payment in an international currency (not USD), this value is in the local currency.
  - `processingOptions` object — Payment processing options
    - `requestPayFaster` boolean — Set as `true` to use BILL Pay Faster. This field is required if `requestCheckDeliveryType` is set. See [Payments](https://developer.bill.com/docs/ap-payments) in the Guides section for information about BILL Pay Faster payments.
    - `createBill` boolean — * Set as `false` to create a vendor payment for an existing bill. * Set as `true` to create a bill for a vendor payment. If `createBill` is `true`, do not set `billId` in your payment request.
    - `requestCheckDeliveryType` 'STANDARD' | 'UPS_1DAY' | 'UPS_2DAY' | 'UPS_3DAY' | 'RTP_DELIVERY' | 'UNDEFINED' — BILL Pay Faster payment delivery type. The `RTP_DELIVERY` option is not available for vendor payments by check.
  - `transactionNumber` string — 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.
  - `confirmationNumber` string — BILL-generated bill payment confirmation value
  - `status` 'APPROVING' | 'SCHEDULED' | 'PAID' | 'CANCELLED' | 'VOID' | 'ESCHEATED' | 'UNDEFINED' — Payment status.
  - `exchangeRate` number — Exchange rate for the payment in an international currency (not USD)
  - `fundingAmount` number — Payment amount in USD
  - `onlinePayment` boolean — 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.
  - `remittanceEmail` string — Remittance email address set for the vendor
  - `createdTime` string, date-time — Payment created date and time
  - `updatedTime` string, date-time — Payment updated date and time
  - `createdBy` string — BILL-generated ID of the user that created the payment. The value begins with `006`.
  - `voidInfo` VoidInfo[] — Void request information
    - `id` string — BILL-generated ID of the void payment request. The value begins with `vrq`.
    - `requestedBy` string — BILL-generated ID of the user that requested a void payment. The value begins with `006`.
    - `type` 'VOID_AND_CREDIT' | 'VOID_AND_REISSUE' | 'VOID_ONLY' | 'VOID_AND_REISSUE_VCARD' — Void payment request type.
    - `status` 'TO_BE_PROCESSED' | 'ACCEPTED' | 'REJECTED' | 'NO_OP' | 'ARCHIVED' — Void payment request status.
    - `reason` string — Void payment request reason
    - `createdTime` string, date-time — Void payment request created date and time
    - `updatedTime` string, date-time — Void payment request updated date and time
  - `disbursementStatus` 'SCHEDULE' | 'DONE' | 'FAILED' | 'VOID' | 'HOLD' | 'FXHOLD' | 'ESCHEATED' | 'UNDEFINED' — Payment disbursement status
  - `disbursementInfo` object — Payment disbursement information. This information is based on the disbursement method used when BILL processes your payment. For example, when BILL processes an ACH payment, `disbursementInfo` includes the `sentDate` and `arrivesByDate` fields.
    - `isVoidable` boolean — Set as `true` if the payment disbursement type can be voided
    - `checkDisbursement` object — Check payment disbursement information
      - `sentDate` string, date — Check payment sent date
      - `arrivesByDate` string, date — Check payment arrives by date
      - `checkNumber` integer — Check number
      - `trackingInformation` string — UPS tracking number for the check. You get a tracking number only for a BILL Pay Faster check payment.
    - `achDisbursement` object — ACH payment disbursement information
      - `sentDate` string, date — ACH payment sent date
      - `arrivesByDate` string, date — ACH payment arrives by date
    - `rppsDisbursement` object — ACH payment to verified national vendor disbursement information
      - `sentDate` string, date — ACH payment to verified national vendor sent date
      - `arrivesByDate` string, date — ACH payment to verified national vendor arrives by date
      - `traceNumber` integer — Payment trace number. This value is used to uniquely identify a payment in a batch.
      - `batchNumber` integer — Payment batch number
    - `internationalDisbursement` object — International ePayment disbursement information
      - `sentDate` string, date — International ePayment sent date
      - `arrivesByDate` string, date — International ePayment arrives by date
      - `amount` number — Disbursement amount
      - `disbursementSubType` 'NONE' | 'WIRE' | 'IACH' | 'LOCAL' | 'MULTIPLE' | 'ACH' | 'UNDEFINED' — Payment delivery method for making the International ePayment
    - `vcardDisbursement` object — Virtual card payment disbursement information
      - `arrivesByDate` string, date — Virtual card payment arrives by date
      - `validUntil` string, date — Date until when the card is valid
      - `last4CardNumber` string — Masked number for virtual card
    - `walletDisbursement` object — Instant Transfer (wallet) payment disbursement information
      - `arrivesByDate` string, date — Instant Transfer (wallet) payment arrives by date
  - `paymentPurpose` object — Payment purpose information
    - `text` string — Payment purpose text
    - `code` object — Payment purpose code
      - `name` string — Name
      - `value` string — Value
  - `cardFundingPurpose` string — Card funding purpose
  - `cancelRequestSubmitted` boolean — 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](https://developer.bill.com/docs/single-status-payment-values) in the Guides section for the list of available values.

## Other responses

- `4XX` — List of errors.
- `5XX` — List of errors.

---

[API](https://skmtc.net/bill/apis/bill-v3-api.md) · [All operations](https://skmtc.net/bill/apis/bill-v3-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bill/bill-v3-api/versions/0483350c434e/schema)