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

# Transaction events

> transaction.* webhooks: when each one fires, the payload it carries, and example deliveries

Endl sends a `transaction.*` webhook when you submit a transaction and each time it
reaches a status you need to act on. Payouts, onramps, offramps and
stablecoin-to-stablecoin transfers all use this one family; **there are no
`payout.*` events**.

| Event | When it fires | `data.status` |
| - | - | - |
| `transaction.initiated` | Once, right after a successful [Submit transaction](https://docs.endl.io/api-reference/transactions/submit-transaction.md) | Usually `INITIATED` |
| `transaction.updated` | Funds are confirmed and the transfer is under way, or the payout was accepted by the receiving rail | `IN_PROGRESS` |
| `transaction.completed` | The transfer settled | `COMPLETE` |
| `transaction.failed` | The transfer was rejected or cancelled and will not settle | `REJECTED`, sometimes `IN_REVIEW` |
| `transaction.refunded` | The funds were returned to the source | `REFUNDED`, sometimes `IN_REVIEW` |

All five events:

* relate to one transaction, so `data.id` is its `txn_…` id and `data.customerId` is the owning customer's `cus_…` id
* use the standard envelope, signature and retry rules from the [Webhooks guide](https://docs.endl.io/guides/webhooks.md)

**Subscribing:** use `"eventFilter": ["transaction.*"]` to receive all of them.

## Payload fields

| Field | Type | Sent on | Description |
| - | - | - | - |
| `id` | string | all | The transaction's id (`txn_…`). The same id [Get transaction](https://docs.endl.io/api-reference/transactions/get-transaction.md) takes. |
| `customerId` | string | all | The customer that owns the transaction (`cus_…`). |
| `status` | string | all | The transaction's status when the event was sent. See [Transaction statuses](https://docs.endl.io/guides/transactions.md). |
| `sourceCurrency` | string | all, when known | The currency the transaction is funded in, e.g. `USDC`. |
| `destinationCurrency` | string | all, when known | The currency the recipient receives, e.g. `INR`. |
| `subStatus` | string | `updated`, `completed`, `failed` on bank payouts | The detailed state, e.g. `WITHDRAWAL_INITIATED` or `TRANSACTION_PROCESSED_SUCCESSFULLY`. Left out on other transactions. |

Standard rendering rules apply: every leaf value is a string, null fields are left
out, keys are sorted, and new fields can appear without a version change. **Amounts,
fees and the FX rate are not in the payload** — read them from Get transaction.

> [!WARNING]
>
> **Go by `eventType`, not `data.status`, for failures and refunds.** Some rails
> report a terminal failure or a return on the sub-status while the status itself
> stays `IN_REVIEW`. Endl sends `transaction.failed` or `transaction.refunded` as
> soon as either says so, so `data.status` on those events can read `IN_REVIEW`.

## Typical lifecycle

```text theme={null}
transaction.initiated        (you submitted)
        │
        ▼
transaction.updated          (IN_PROGRESS — may arrive more than once, or not at all)
        │
        ├──► transaction.completed   (COMPLETE, final)
        ├──► transaction.failed      (final)
        └──► transaction.refunded    (final)
```

Things to know:

* **`transaction.updated` is optional.** A fast transfer can settle during submit,
  so `transaction.completed` may follow `transaction.initiated` directly.
* **`transaction.updated` can repeat**, for example once when the funds are
  confirmed and again when the payout is accepted by the receiving rail. Check
  `subStatus` to tell them apart.
* **Holds send nothing.** `IN_REVIEW` (compliance review) and `PENDING_TRAVEL_RULE`
  are internal holds and emit no event. If a transfer goes quiet, poll Get transaction.
* **POBO transactions don't emit these events.** Transactions submitted through the
  [POBO endpoints](https://docs.endl.io/api-reference/pobo/introduction.md) are tracked through those endpoints instead.
* **Order isn't guaranteed across retries.** Never move a transaction back from a
  final state because an older `transaction.updated` arrived late.

## Events in detail

### transaction.initiated

**When:** your Submit transaction call succeeded. Sent once per transaction.

**What to do:** store the `txn_` id against your own payment and show it as
"processing". Wait for a final event.

```json theme={null}
{
  "eventId": "4e1d9a72-8c3b-3f50-a2d1-6b7c0e9f1a23",
  "eventType": "transaction.initiated",
  "eventCategory": "transaction",
  "eventCreatedAt": "2026-11-03T10:12:04.118Z",
  "version": "2026-09.1",
  "data": {
    "id": "txn_4Fq9ZkLm2RtY7uWx0aBc",
    "customerId": "cus_8Hn2PqRs5TvW1xYz3dEf",
    "destinationCurrency": "INR",
    "sourceCurrency": "USDC",
    "status": "INITIATED"
  }
}
```

### transaction.updated

**When:** the transaction moved to `IN_PROGRESS` — funds confirmed and the transfer
under way, or a bank payout accepted by the receiving rail.

**What to do:** nothing is required. Update your own status if you show progress.

```json theme={null}
{
  "eventId": "b7c2e4f1-0a9d-3c68-91e5-2f4a8d6b0c37",
  "eventType": "transaction.updated",
  "eventCategory": "transaction",
  "eventCreatedAt": "2026-11-03T10:13:41.902Z",
  "version": "2026-09.1",
  "data": {
    "id": "txn_4Fq9ZkLm2RtY7uWx0aBc",
    "customerId": "cus_8Hn2PqRs5TvW1xYz3dEf",
    "destinationCurrency": "INR",
    "sourceCurrency": "USDC",
    "status": "IN_PROGRESS",
    "subStatus": "WITHDRAWAL_INITIATED"
  }
}
```

### transaction.completed

**When:** the transfer settled. The status is `COMPLETE`, and it's final.

**What to do:** mark the payment as paid. Call Get transaction if you need the final
amounts or fees.

```json theme={null}
{
  "eventId": "9f0e1d2c-3b4a-3958-8776-a5b4c3d2e1f0",
  "eventType": "transaction.completed",
  "eventCategory": "transaction",
  "eventCreatedAt": "2026-11-03T10:21:15.330Z",
  "version": "2026-09.1",
  "data": {
    "id": "txn_4Fq9ZkLm2RtY7uWx0aBc",
    "customerId": "cus_8Hn2PqRs5TvW1xYz3dEf",
    "destinationCurrency": "INR",
    "sourceCurrency": "USDC",
    "status": "COMPLETE",
    "subStatus": "TRANSACTION_PROCESSED_SUCCESSFULLY"
  }
}
```

### transaction.failed

**When:** the transfer was rejected or cancelled and will not settle — by
compliance, by Endl, or by the receiving rail. Final.

**What to do:** mark the payment as failed and call Get transaction for the reason.
To try again, generate a new quote and submit a new transaction.

```json theme={null}
{
  "eventId": "1a2b3c4d-5e6f-3a7b-8c9d-0e1f2a3b4c5d",
  "eventType": "transaction.failed",
  "eventCategory": "transaction",
  "eventCreatedAt": "2026-11-03T11:02:48.075Z",
  "version": "2026-09.1",
  "data": {
    "id": "txn_7Lm3NpQr5StU7vWx9yZa",
    "customerId": "cus_8Hn2PqRs5TvW1xYz3dEf",
    "destinationCurrency": "AED",
    "sourceCurrency": "USD",
    "status": "REJECTED",
    "subStatus": "TRANSACTION_REJECTED"
  }
}
```

### transaction.refunded

**When:** the funds were returned to the source, for example because the
recipient's bank returned the payment. Final.

**What to do:** mark the payment as refunded and reconcile the returned funds. Note
that `data.status` can read `IN_REVIEW` here — see the warning above.

```json theme={null}
{
  "eventId": "6d5c4b3a-2f1e-3d0c-9b8a-7f6e5d4c3b2a",
  "eventType": "transaction.refunded",
  "eventCategory": "transaction",
  "eventCreatedAt": "2026-11-04T08:40:19.660Z",
  "version": "2026-09.1",
  "data": {
    "id": "txn_2Bc4De6Fg8Hi0Jk2Lm4N",
    "customerId": "cus_8Hn2PqRs5TvW1xYz3dEf",
    "destinationCurrency": "EUR",
    "sourceCurrency": "USD",
    "status": "IN_REVIEW"
  }
}
```

## Best practices

* **Verify the signature, then deduplicate on `eventId`, then act.** Delivery is at
  least once, so the same event can arrive twice.
* **Treat `completed`, `failed` and `refunded` as final.** Ignore any later
  `transaction.updated` for the same `txn_` id.
* **Use the API as the source of truth.** Webhooks tell you that something changed;
  [Get transaction](https://docs.endl.io/api-reference/transactions/get-transaction.md) tells you the full
  state, including amounts and fees.
* **Subscribe with `transaction.*`** so you automatically receive new transaction
  events Endl adds later.


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