> 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/transactions.md).

# Transactions

The transaction object and the allowed CRUD operations on the related resource endpoint

Transactions are created during an order lifecycle and determine its payment status changes:

* [Authorizations](/core-api-reference/authorizations.md) — when a payment source is authorized. On successful authorization, the order's payment status becomes `authorized`.
* [Captures](/core-api-reference/captures.md) — when an authorization is captured. On successful capture, the order's payment status becomes `paid`.
* [Voids](/core-api-reference/voids.md) — when an authorization is voided. On successful void, the order's payment status becomes `voided`.
* [Refunds](/core-api-reference/refunds.md) — when a capture is refunded, either totally or partially. On successful refund, the order's payment status becomes `refunded` or `partially_refunded`.

Fetching a transaction returns all the information and messages provided by the [payment gateway](/core-api-reference/payment_gateways.md).

## Additional data

The `additional_data` attribute stores any extra information the payment gateway returns alongside the transaction outcome (e.g. the payer's details for wallet payments, or the recurring references for tokenized payment sources). The content is read-only and its structure depends entirely on the gateway, so make sure to check the gateway's documentation before relying on specific keys.

{% hint style="info" %}
At the moment, the `additional_data` attribute is populated for [Adyen](/core-api-reference/adyen_gateways.md) transactions only, with the `additionalData` object received via the gateway's webhook notifications (the HMAC signature is always stripped out). If a transaction receives more than one notification, the latest one overrides the previous content. For all the other payment gateways, the attribute is `null`.
{% endhint %}

## Unblocking stuck transactions

If a transaction gets stuck (for any reason) on our platform but succeeds on the payment gateway, you can patch it (by using [integration](/core/api-credentials.md#integration) API credentials on the specific transaction type endpoint) with the `_forward` trigger attribute set to `true`. In this case, some checks are performed:

* The transaction's relative balance must be positive.
* The transaction's `succeeded` attribute must be `false`.
* The associated order's payment status must be eligible to be forwarded successfully (e.g. from `authorized` to `paid`).

If all of these guards pass, the transaction is marked as succeeded and the order's payment status is updated accordingly. Otherwise, no action will be performed without returning any error.

{% hint style="warning" %}
When patching authorizations, the order is also placed at the end of the forwarding process, to avoid any possible modifications.
{% endhint %}

## Cancelling transactions

If an authorization or capture succeeded, but the associate order is still pending, it can happen that the order is updated and its total amount differs from the authorized or captured one. In this case, you must reset the related transaction by patching it (you need to use [integration](/core/api-credentials.md#integration) API credentials on the specific transaction type endpoint) with the `_cancel` trigger attribute set to `true`. At the end of the process, the order payment status will still be `unpaid` so that the payment can be completed with a different payment source.

{% hint style="warning" %}
The above scenario can occur for example when the 3DS is enabled for those payment gateways where that security measure is performed as a separate step (e.g. [Adyen](/core-api-reference/adyen_gateways.md)). To avoid any possible order changes upon receiving a succeeded authorization or (if [auto-capture](/how-tos/placing-orders/auto-capture.md) is enabled) capture, we recommend to place the order as first thing (i.e. before authorization) in your payment workflow.
{% endhint %}

{% hint style="info" %}
This is an **immutable API**, meaning that create, update, and delete operations are not allowed on this endpoint. You can only fetch a list of transactions or a single transaction object. For the full set of available CRUD actions to the specific transaction type endpoints.
{% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.commercelayer.io/core-api-reference/transactions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.