Sign in

v1

latestOpenAPI 3.0.12026-07-24310590875.6 KB
payments

Void a payment

Void an existing payment.

Void a bill payment that has started processing and cannot be canceled (with POST /v3/payments/{paymentId}/cancel). You can attempt to void payments made both with BILL (online) and outside BILL (offline).

Void a payment made with BILL (online)

In your /POST /v3/payments/{paymentId}/void request:

  • Set paymentId as the BILL-generated ID of the payment. The value begins with stp.
  • Set type as the void payment request type
  • Set reason as the reason for voiding the payment

See Can I cancel or void a Payables payment? in the BILL Help Center to learn about the BILL void payment process and timing in the production environment.

post/v3/payments/{paymentId}/void

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

Request body

type'VOID_AND_CREDIT' | 'VOID_AND_REISSUE' required

Void payment request type

reasonstring required

Void payment request reason

Response

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