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

# Deposit events

> deposit.* webhooks: when money arriving into a customer's account is seen, credited or cancelled

Endl sends a `deposit.*` webhook when money arrives into one of your customers'
accounts — a bank transfer into a virtual account, or a crypto transfer into a
deposit address. **Money landing in an account is a deposit event, not an account
event.**

| Event | When it fires | `data.status` |
| - | - | - |
| `deposit.created` | A deposit has been seen and authorised but not yet credited | `INITIATED` |
| `deposit.received` | The funds have been credited | `COMPLETE` |
| `deposit.failed` | The deposit was cancelled and will not be credited | `REJECTED` |

All three events:

* relate to one deposit, so `data.id` is its `dep_…` 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": ["deposit.*"]` to receive all of them.

## Payload fields

| Field | Type | Sent on | Description |
| - | - | - | - |
| `id` | string | all | The deposit's id (`dep_…`). |
| `customerId` | string | all | The customer whose account received the deposit (`cus_…`). |
| `status` | string | all | `INITIATED`, `COMPLETE` or `REJECTED`. |
| `rail` | string | all, when known | How the money arrived. See [Rails](#rails). |
| `amountReceived` | string | `deposit.received`; others when known | The amount credited, as a decimal string, e.g. `"2500.00"`. |

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.

> [!NOTE]
>
> **The payload has no currency or account field.** Match the deposit to the
> customer with `data.customerId`, and take the currency from the account the funds
> were sent to.

## Rails

| `rail` | Meaning |
| - | - |
| `ACH`, `FEDWIRE` | US bank transfer |
| `SEPA`, `SEPA_CT` | Euro bank transfer |
| `SWIFT` | International wire |
| `FPS`, `CHAPS` | UK bank transfer |
| `EFT` | Canadian bank transfer |
| `IMPS`, `UPI` | Indian bank transfer |
| `PIX` | Brazilian instant payment |
| `SPEI` | Mexican bank transfer |
| `AED_LOCAL` | UAE local bank transfer |
| `CRYPTO` | Stablecoin transfer to a deposit address |
| `ENDL_ACCOUNT`, `TOPUP_FIAT` | Funding from within Endl |

Treat the list as open-ended: new rails can appear.

## Typical lifecycle

```text theme={null}
deposit.created      (INITIATED — seen, not yet credited)
      │
      ├──► deposit.received   (COMPLETE, final)
      └──► deposit.failed     (REJECTED, final)
```

Things to know:

* **`deposit.created` is optional.** Many deposits, crypto ones especially, are only
  seen once they have landed, so `deposit.received` can be the first and only event.
* **The pending state sends nothing.** A deposit in `PENDING` emits no event; the
  next one you get is `deposit.received` or `deposit.failed`.
* **The partner's own funding is excluded.** Deposits into your own POBO funding
  account are not customer deposits and emit no event.
* **Order isn't guaranteed across retries.** A late `deposit.created` must never
  overwrite a deposit you already marked as received.

## Events in detail

### deposit.created

**When:** the deposit has been seen and authorised by the receiving rail but not yet
credited.

**What to do:** show the money as incoming. Don't release goods or credit a balance yet.

```json theme={null}
{
  "eventId": "2c3d4e5f-6a7b-3c8d-9e0f-1a2b3c4d5e6f",
  "eventType": "deposit.created",
  "eventCategory": "deposit",
  "eventCreatedAt": "2026-11-03T14:05:12.204Z",
  "version": "2026-09.1",
  "data": {
    "id": "dep_9Rc4StUv6WxY8zAb0cDe",
    "customerId": "cus_8Hn2PqRs5TvW1xYz3dEf",
    "rail": "ACH",
    "status": "INITIATED"
  }
}
```

### deposit.received

**When:** the funds have been credited to the customer's account. Final.

**What to do:** credit the customer in your own ledger, using `amountReceived`.

```json theme={null}
{
  "eventId": "8e7d6c5b-4a3f-3e2d-9c1b-0a9f8e7d6c5b",
  "eventType": "deposit.received",
  "eventCategory": "deposit",
  "eventCreatedAt": "2026-11-03T16:31:47.919Z",
  "version": "2026-09.1",
  "data": {
    "id": "dep_9Rc4StUv6WxY8zAb0cDe",
    "customerId": "cus_8Hn2PqRs5TvW1xYz3dEf",
    "amountReceived": "2500.00",
    "rail": "ACH",
    "status": "COMPLETE"
  }
}
```

A crypto deposit looks the same with `"rail": "CRYPTO"`:

```json theme={null}
{
  "eventId": "5a6b7c8d-9e0f-3a1b-8c2d-3e4f5a6b7c8d",
  "eventType": "deposit.received",
  "eventCategory": "deposit",
  "eventCreatedAt": "2026-11-03T09:12:03.551Z",
  "version": "2026-09.1",
  "data": {
    "id": "dep_3Hj5Kl7Mn9Pq1Rs3Tu5V",
    "customerId": "cus_8Hn2PqRs5TvW1xYz3dEf",
    "amountReceived": "1000.000000",
    "rail": "CRYPTO",
    "status": "COMPLETE"
  }
}
```

### deposit.failed

**When:** the deposit was cancelled before it was credited, for example because the
sending bank recalled it. Final.

**What to do:** remove the incoming amount you showed on `deposit.created`.

```json theme={null}
{
  "eventId": "0f1e2d3c-4b5a-3f6e-8d7c-9b0a1f2e3d4c",
  "eventType": "deposit.failed",
  "eventCategory": "deposit",
  "eventCreatedAt": "2026-11-04T10:48:30.007Z",
  "version": "2026-09.1",
  "data": {
    "id": "dep_9Rc4StUv6WxY8zAb0cDe",
    "customerId": "cus_8Hn2PqRs5TvW1xYz3dEf",
    "rail": "ACH",
    "status": "REJECTED"
  }
}
```

## Best practices

* **Verify the signature, then deduplicate on `eventId`, then act.** Delivery is at
  least once, so the same event can arrive twice.
* **Credit only on `deposit.received`.** `deposit.created` means "on its way", not
  "arrived".
* **Treat `received` and `failed` as final.** Ignore any later `deposit.created`
  for the same `dep_` id.
* **Subscribe with `deposit.*`** so you automatically receive new deposit events
  Endl adds later.


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