Cancel Payment (Void)

Cancel an authorized payment that has not yet been captured. The authorization hold on the cardholder's funds is released immediately.

When to Use

  • You placed a authorization (payment_type=AUTH) but decided not to charge the customer
  • Fraud signals triggered after authorization
  • Order cancelled by the customer before fulfilment
  • Inventory unavailable after authorization

Do not use this endpoint when:

Endpoint

POST https://api.sandbox.build.app/api/v1/acq/payment/{payment_id}/cancel

Integration Flow

Cancel Flow

State Transitions

Cancel State

The Payment object's payment_status moves SUCCEEDED → CANCELING → CANCELED. In rare failure cases the status becomes CANCELED_FAILED and must be resolved through support.

Best Practices

  • Always pass merchant_request_id. Retries with the same value return the original cancellation result within the 24-hour idempotency window.
  • Check the Payment state first. If you query the payment and it is already in CAPTURED or a terminal state, do not call /cancel — it will error.
  • Full cancellation only. Partial release of authorization is not supported.
  • Act quickly. Most card networks allow cancel only on T+0 (the same day as authorization). After that, funds may already be in the clearing pipeline and you must refund.
  • Pair with webhook CANCEL. Do not rely on the synchronous API response alone; reconcile final state via webhooks.

FAQ

Q: What is the difference between Cancel and Refund? A: Cancel releases an authorization hold — no money ever moved, so no transfer happens. Refund reverses a completed charge and initiates a return of funds that have already left the cardholder's account. Void is faster and cheaper when it applies.

Q: How long do I have to cancel an authorization? A: It depends on the payment method and issuer, but the safe assumption is "same day" (T+0). After authorization is settled, you must refund.

Q: Does cancel produce a chargeback-like record for the cardholder? A: No. A successful cancel typically vanishes from the cardholder's pending transactions with no statement entry. A refund, by contrast, creates two entries (original charge + reversal).

Q: What if I call /cancel on an already-cancelled payment? A: The request is idempotent if you reuse the original merchant_request_id. Otherwise you'll get an error indicating the payment is already in a terminal state.

Next Steps