Sign in

v1

latestOpenAPI 3.0.12026-07-24310590875.6 KB
payments

Cancel a payment

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.

post/v3/payments/{paymentId}/cancel

Path parameters

paymentIdstring required

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

Example:{{payment_id}}

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

Response

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