> For the complete documentation index, see [llms.txt](https://developers.coincircuit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coincircuit.io/webhooks/readme/payouts.md).

# Payouts

Payout webhook events and example payloads.

Payout webhooks track outgoing transfers to recipients.

The examples on this page show crypto payouts. Bank payouts use the same events and shape, with `method` set to `fiat` and a bank account recipient.

### Field descriptions

Payout webhook events use `data.payout`.

| Field                                         | Type             | Description                                                       |
| --------------------------------------------- | ---------------- | ----------------------------------------------------------------- |
| `data.payout.id`                              | `string`         | Unique payout identifier.                                         |
| `data.payout.reference`                       | `string \| null` | Payout reference.                                                 |
| `data.payout.method`                          | `string`         | `crypto` or `fiat`.                                               |
| `data.payout.type`                            | `string`         | `instant`, `withdrawal`, or `refund`.                             |
| `data.payout.status`                          | `string`         | Payout status. See each event below.                              |
| `data.payout.amount`                          | `string`         | Amount the recipient receives.                                    |
| `data.payout.fee`                             | `string`         | Fee charged for the payout.                                       |
| `data.payout.total`                           | `string`         | Total taken from your balance (amount plus fee).                  |
| `data.payout.currency`                        | `string`         | Payout currency, such as `NGN` or `USDT`.                         |
| `data.payout.conversion`                      | `object \| null` | Conversion details, when the payout converted between currencies. |
| `data.payout.narration`                       | `string \| null` | Payout narration.                                                 |
| `data.payout.recipient`                       | `object`         | Recipient details. The shape of `details` depends on `type`.      |
| `data.payout.recipient.id`                    | `string \| null` | ID of the saved recipient (crypto address or bank account).       |
| `data.payout.recipient.type`                  | `string`         | `crypto_address` or `ngn_bank_account`.                           |
| `data.payout.recipient.details.chain`         | `string \| null` | Blockchain network. `crypto_address` only.                        |
| `data.payout.recipient.details.address`       | `string \| null` | Destination wallet address. `crypto_address` only.                |
| `data.payout.recipient.details.accountName`   | `string \| null` | Account holder name. `ngn_bank_account` only.                     |
| `data.payout.recipient.details.accountNumber` | `string \| null` | Masked account number. `ngn_bank_account` only.                   |
| `data.payout.recipient.details.bankName`      | `string \| null` | Bank name. `ngn_bank_account` only.                               |
| `data.payout.recipient.details.bankCode`      | `string \| null` | Bank code. `ngn_bank_account` only.                               |
| `data.payout.recipient.details.accountType`   | `string \| null` | Account type. `ngn_bank_account` only.                            |
| `data.payout.recipient.details.currency`      | `string \| null` | Account currency. `ngn_bank_account` only.                        |
| `data.payout.channel`                         | `string`         | Where the payout was requested: `API` or `dashboard`.             |
| `data.payout.txHash`                          | `string \| null` | Transaction hash on the blockchain, for crypto payouts.           |
| `data.payout.completedAt`                     | `string`         | When the payout completed. Sent only with `payout.success`.       |
| `data.payout.failureReason`                   | `string`         | Why the payout failed. Sent only with `payout.failed`.            |
| `data.payout.createdAt`                       | `string`         | When the payout was created (ISO 8601).                           |
| `data.payout.updatedAt`                       | `string`         | When the payout was last updated (ISO 8601).                      |

### Events

* `payout.created`
* `payout.success`
* `payout.failed`

### `payout.created`

Sent when a payout is created. `data.payout.status` is `pending`.

Use this event to track payout initiation.

```json
{
  "event": "payout.created",
  "data": {
    "payout": {
      "id": "po_123",
      "reference": "PAY-ABC123DEF456",
      "method": "crypto",
      "type": "withdrawal",
      "status": "pending",
      "amount": "99.50",
      "fee": "0.50",
      "total": "100.00",
      "currency": "USDT",
      "narration": "Withdrawal payout",
      "recipient": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "crypto_address",
        "details": {
          "chain": "ethereum",
          "address": "0x1234567890abcdef1234567890abcdef12345678"
        }
      },
      "channel": "API",
      "txHash": null,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  }
}
```

### `payout.success`

Sent when a payout reaches the recipient. `data.payout.status` is `success`.

Use this event to close the payout in your ledger.

```json
{
  "event": "payout.success",
  "data": {
    "payout": {
      "id": "po_123",
      "reference": "PAY-ABC123DEF456",
      "method": "crypto",
      "type": "withdrawal",
      "status": "success",
      "amount": "99.50",
      "fee": "0.50",
      "total": "100.00",
      "currency": "USDT",
      "narration": "Withdrawal payout",
      "recipient": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "crypto_address",
        "details": {
          "chain": "ethereum",
          "address": "0x1234567890abcdef1234567890abcdef12345678"
        }
      },
      "channel": "API",
      "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "completedAt": "2024-01-15T10:40:00.000Z",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:40:00.000Z"
    }
  }
}
```

### `payout.failed`

Sent when a payout fails. `data.payout.status` is `failed`.

Use this event to stop reconciliation and surface the error.

{% hint style="danger" %}
Check `data.payout.failureReason` for why the payout failed.
{% endhint %}

```json
{
  "event": "payout.failed",
  "data": {
    "payout": {
      "id": "po_123",
      "reference": "PAY-ABC123DEF456",
      "method": "crypto",
      "type": "withdrawal",
      "status": "failed",
      "amount": "99.50",
      "fee": "0.50",
      "total": "100.00",
      "currency": "USDT",
      "narration": "Withdrawal payout",
      "recipient": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "crypto_address",
        "details": {
          "chain": "ethereum",
          "address": "0x1234567890abcdef1234567890abcdef12345678"
        }
      },
      "channel": "API",
      "txHash": null,
      "failureReason": "Invalid address",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  }
}
```