> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core-api-reference/2026-05/payment_voids.md).

# Payment voids

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

A payment void cancels a [payment authorization](/core-api-reference/2026-05/payment_authorizations.md) before any funds have been captured. The transaction is processed asynchronously — on success, the [payment session](/core-api-reference/2026-05/payment_sessions.md) 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](/core-api-reference/2026-05/payment_settings.md).

## 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](/core-api-reference/2026-05/payment_captures.md) 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).

{% hint style="info" %}
A void must reference a payment authorization at creation time. Only one succeeded void per authorization — and per session — is allowed.
{% endhint %}

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

{% hint style="warning" %}
Only one void can ever succeed per authorization — and per session — no matter how many attempts preceded it. If a succeeded void already exists and another one would also succeed, that attempt is rejected with a `422 Unprocessable Entity` error instead.
{% endhint %}

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

{% hint style="info" %}
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.
{% endhint %}

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

* [Adyen](/core-api-reference/2026-05/payment_setting_adyens.md), [Checkout.com](/core-api-reference/2026-05/payment_setting_checkout_coms.md), and [Stripe](/core-api-reference/2026-05/payment_setting_stripes.md) — the missing authorization is synthesized from the event itself, so the void can still be created and the session kept in sync.
* [External](/core-api-reference/2026-05/payment_setting_externals.md) (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](/core-api-reference/2026-05/payment_setting_braintrees.md) — Braintree voids are always API-initiated and processed synchronously against the gateway, so there's no webhook event to cascade from.
* [PayPal](/core-api-reference/2026-05/payment_setting_paypals.md) — 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.commercelayer.io/core-api-reference/2026-05/payment_voids.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.