> 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_authorizations.md).

# Payment authorizations

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

A payment authorization is the first transaction in a payment session's [lifecycle](/core-api-reference/2026-05/payment_sessions.md#lifecycle). The transaction is processed asynchronously — on success, it reserves the session amount on the customer's payment instrument without collecting funds, transitioning the payment session to `authorized` status.

Fetching a payment authorization returns all information and messages provided by the [payment setting](/core-api-reference/2026-05/payment_settings.md). To collect or cancel the reserved funds, create a [payment capture](/core-api-reference/2026-05/payment_captures.md) or [payment void](/core-api-reference/2026-05/payment_voids.md) referencing this authorization.

## Authorization amount

The authorization amount always matches the payment session amount exactly. You cannot authorize a partial amount — if you need to collect a different amount, adjust it at the session level before authorizing.

{% hint style="info" %}
Each payment session can have at most one succeeded authorization. The authorization amount is set automatically to the session amount and cannot be changed.
{% endhint %}

## Retrying a failed attempt

The gateway's confirmation can fail before ever reaching `succeeded` — for example, a customer failing a 3DS challenge. A pre-success failure doesn't touch the session itself, so you can create a new payment authorization for the same session to retry, without needing to start over with a new session. Retrying on the same session also requires that the session not have expired.

{% hint style="warning" %}
Gift cards are the one exception. There, a pre-success failure [invalidates](#invalidation) the session itself, which is terminal — no further transaction can be created against it, so retrying means creating a new payment session rather than a new authorization.
{% endhint %}

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

## Capture and void balances

A payment authorization tracks two balance attributes:

* `capture_balance_cents` — the amount still available for capture (session amount minus already captured amounts).
* `void_balance_cents` — the amount still available to void (zero once the authorization has been voided).

{% hint style="info" %}
Both balances are attributes on the authorization itself. They update as captures and voids are created against it.
{% endhint %}

## Event-driven creation

Gateway webhook events can create a payment authorization automatically if one does not already exist for the session. 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.

When the session already has an authorization, the incoming event updates that one rather than adding a second. The session's current authorization is the succeeded one if any exists, or otherwise the most recent attempt.

{% hint style="warning" %}
A failed attempt is never revived by a later event, since a failed transaction is final. Retrying is an API-initiated operation: create a new payment authorization against the session, and it becomes the session's current one. An integration driven purely by webhooks, with no API call of its own, cannot retry after a failure.
{% endhint %}

{% 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.
{% endhint %}

## Invalidation

An authorization can end up `invalidated` two different ways, both outside your control:

* **Gateway reversal** — A gateway occasionally reverses its own earlier success, for example an issuer approving a payment and then declining it minutes later once risk or fraud checks complete. When this happens, Commerce Layer moves the authorization from `succeeded` to whichever negative status the gateway's event maps to — `declined`, `failed`, `canceled`, or `expired` — and marks the payment session as `invalidated`, since the funds it reported as reserved never actually were.
* **Gift card failure** — The authorization attempt fails outright, without ever reaching `succeeded`, because the gift card can no longer be resolved or its balance is insufficient by the time authorization runs (more details [here](/core-api-reference/2026-05/payment_setting_gift_cards.md#invalidation-at-authorization)).

{% hint style="warning" %}
Invalidation isn't something you trigger directly, unlike a payment void. Once a session is `invalidated`, it's terminal, the same as a `voided` one: no further transaction can be created against it.
{% endhint %}

## Handling 3DS and customer action

For gateways whose SCA/3DS challenge requires multiple steps, the authorization may transition to `requires_action` instead of proceeding directly to `succeeded`. In that case, `next_action_type` and `next_action_data` are populated to tell the client what to do next:

* `next_action_type` — the kind of action required from the customer. One of `redirect`, `challenge`, `fingerprint`, or `present`.
* `next_action_data` — the gateway-specific data needed to perform that action (e.g. the redirect URL, the challenge or fingerprinting payload, etc.).

Both attributes are `null` once the authorization leaves `requires_action`. How the flow resumes depends on the gateway:

* **Client-side submission** — after the customer completes the challenge, the client must update the authorization and pass the `_payment_details` trigger attribute to submit the result and drive the transaction to its final state.
* **Event-driven** — the authorization status is updated automatically when the payment provider fires the corresponding webhook event. No additional API call is needed.

{% hint style="warning" %}
An authorization that renews an [order subscription](/core-api-reference/2026-05/order_subscriptions.md#unattended-renewals) never waits for customer action: nobody is there to take it. An instrument that turns out to require authentication is declined for that run instead of moving to `requires_action`.
{% endhint %}

{% hint style="info" %}
[Sales channel](/core/api-credentials.md#sales-channel) API credentials can read a payment authorization for as long as its order hasn't been approved yet — covering the full authorization lifecycle through to a `succeeded`, `declined`, or `failed` outcome, not just while it's still `pending`. This lets a client safely poll the authorization to detect the outcome of an event-driven or asynchronous update.
{% endhint %}


---

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