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).
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.
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_tokenfor the authorization. If it's missing, the event is rejected with a422 Unprocessable Entityresponse.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