> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dintero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout Webhook

> Subscribe to Dintero checkout_transaction webhook events to get notified when a transaction is created, captured, refunded, or voided in real time.

Create a webhooks subscription on `checkout_transaction` event to receive notification
when new transaction is created or updated (captured/refunded or voided)

```json theme={null}
POST https://api.dintero.com/v1/accounts/{ACCOUNT_ID}/hooks/subscriptions
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "config": {
    "url": "https://example.com/checkout-transaction",
    "content_type": "application/json"
  },
  "events": [ "checkout_transaction" ]
}
```

> [!NOTE]
>
> See \[Webhooks] for more information about creating webhook subscription

### Checkout transaction event

Example of event a subscription can receive

```json theme={null}
{
  "account_id": "P12345678",
  "event": "checkout_transaction",
  "event_delivery": "9ebb6d41-dca5-484e-8330-9c9fa96b60ba",
  "transaction": {
    "id": "P12345678.465UfBENeLpkBvwmqfTC4k",
    "session_id": "P12345678.465U8CUzaPVpneu1wt8Wei",
    "merchant_reference": "ORDER-123",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "merchant_reference_2": "OTHER-ID-123",
    "status": "AUTHORIZED"
  }
}
```

> [!NOTE]
>
> See Checkout API to get more details about the transaction object
> included in the event
>
> * \[GET /v1/transaction/\{id}]\[GET /v1/transaction/{id}]

### Handling corrected events

An event on a transaction can include a `correction` object when the event's
own outcome didn't reflect the transaction's actual state. For example, a
capture can time out without a confirmed result even though the transaction was
captured. When this happens, Dintero adds a later event whose `correction`
object gives the real status and references the event(s) that rectify the transaction:

* `correction.status`: The transaction status to use once this event is
  applied. Use this value to determine the transaction status.
* `correction.event_ids`: The IDs of the earlier events that have been added
  to rectify the transaction. It can be an empty array if no correction events were
  necessary.

See [GET /v1/transaction/\{id}][GET /v1/transaction/{id}] for the full `correction` object.

Note that you do not get a separate notification for correction events that are added
to rectify the transaction state.

> [!WARNING]
>
> A `success: false` value and an `error` object describe the event operation,
> not the transaction's final outcome. Always check `correction.status` first when a
> `correction` object is present.

See below for an example transaction:

```json theme={null}
{
  "id": "P12345678.465UfBENeLpkBvwmqfTC4k",
  "status": "CAPTURED",
  "events": [
    ...
    {
      "id": "3",
      "event": "CAPTURE",
      "success": false,
      "error": { ... },
      "correction": {
        "status": "AUTHORIZED",
        "event_ids": [],
        "remaining_void_amount": 10000,
        "remaining_refund_amount": 0,
        "remaining_capture_amount": 10000
      },
      "transaction_status": "AUTHORIZED"
    },
    {
      "id": "4",
      "event": "CAPTURE",
      "amount": 10000,
      "success": true,
      "transaction_status": "UNKNOWN"
    },
    {
      "id": "5",
      "event": "CAPTURE",
      "success": false,
      "error": { ... },
      "transaction_status": "CAPTURED",
      "correction": {
        "status": "CAPTURED",
        "event_ids": ["4"],
        "remaining_capture_amount": 0,
        "remaining_refund_amount": 10000,
        "remaining_void_amount": 0
      }
    }
  ]
}
```

Event `3` is a capture attempt that initially appears to fail. Its `correction.status`
is `AUTHORIZED` with an empty `event_ids`, meaning no correction was done and the
transaction appeared to remain authorized.

Event `5` is a second capture attempt, but it fails as the transaction was
already captured (event `3` actually succeeded). So the event gets `success=false`,
but includes a `correction` pointing to event `4`, which is the result of the
successful capture. The transaction status after the second capture can be
determined from `correction.status` in event `5`.

In this example, you receive notifications for events `3` and `5`. You do not
receive a notification for correction event `4`, so handle it when you receive
the notification for event `5`.

Note that in the above example you will get callbacks for event `3` and
event `5`. There is no callback for the correction event `4`, this needs to be handled
when receiving the callback for event `5`.

[Webhooks]: /docs/checkout/webhooks.md

[GET /v1/transaction/{id}]: /api-reference/transactions/transactions_id_get.md


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.