Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
Beta

Payment voids

The payment void object and the allowed CRUD operations on the related resource endpoint

A payment void cancels a payment authorization before any funds have been captured. The transaction is processed asynchronously — on success, the payment session transitions to voided status and the reserved funds are released on the customer's payment instrument.

Fetching a payment void returns all the information and messages provided by the payment setting.

Void amount

The void amount always matches the authorization amount exactly — a void cancels the entire authorization, releasing the full reserved amount immediately. There's no partial void: if you only need part of the authorized amount, create a partial capture for what you need instead — the remaining reserved funds will be released automatically once the authorization expires (timing depends on the payment gateway and the type of payment instrument).

A void must reference a payment authorization at creation time. Only one succeeded void per authorization — and per session — is allowed.

Retrying a failed attempt

A void can fail asynchronously before ever reaching succeeded. Since a pre-success failure doesn't affect the authorization or the session, you can create another payment void referencing the same authorization to retry.

Event-driven creation

Gateway webhook events can create a payment void automatically if one does not already exist for the authorization. This means a transaction does not need to be explicitly created via the API first — Commerce Layer will create it in response to the event, ensuring the session status and order payment status are always kept in sync regardless of whether the flow was API-initiated or event-driven.

Incoming events are matched to an existing void by the gateway's own reference for that operation. A reference already seen updates the void it belongs to, while a reference not seen before creates a new one — so a second void attempt — carrying a new reference — gets its own record and can succeed normally even if an earlier attempt failed.

Gateways don't guarantee delivery order and may send the same event more than once. An event arriving for a transaction that has already reached a final status is ignored, so a redelivery can't overwrite a settled outcome or duplicate a transaction that was already recorded.

If a void (cancellation) event arrives and the corresponding payment authorization is missing, behavior depends on the gateway:

  • Adyen, Checkout.com, and Stripe — the missing authorization is synthesized from the event itself, so the void can still be created and the session kept in sync.

  • External (custom gateways) — the webhook payload must explicitly include the reference_transaction_token for the authorization. If it's missing, the event is rejected with a 422 Unprocessable Entity response.

  • Braintree — Braintree voids are always API-initiated and processed synchronously against the gateway, so there's no webhook event to cascade from.

  • PayPal — void events do not cascade. A void is only created if the payment authorization already exists for the session. Otherwise, the event is silently dropped.

Last updated