---
title: "Cancel a payment"
method: POST
path: "/v3/payments/{paymentId}/cancel"
tags: ["payments"]
---

# Cancel a payment

`POST /v3/payments/{paymentId}/cancel`

Cancel an existing payment.

You can cancel a payment only when the payment `singleStatus` is `SCHEDULED`. When BILL starts processing the payment, the payment `singleStatus` changes. At that point, you cannot cancel the payment. You can attempt to void the payment with `POST /v3/payments/{paymentId}/void`.

## Path parameters

- `paymentId` string, required — BILL-generated ID of the payment. The value begins with `stp`.

## Headers

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

## Response `200`

Cancel 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)