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

# Withdrawal event

This webhook event notifies your application when withdrawal (payout) events occur. You receive events across the full lifecycle of a payout: `PENDING` when initiated, `PROCESSING_PAY_OUT` when accepted by the payment network (ACH/RTP only), `SUCCESS` when settled, and `FAILED` if the payout could not be completed.

## Event Schema

| Field                   | Type   | Description                                                                               |
| ----------------------- | ------ | ----------------------------------------------------------------------------------------- |
| `eventType`             | string | Always `WITHDRAWAL`                                                                       |
| `status`                | string | `PENDING`, `PROCESSING_PAY_OUT`, `SUCCESS`, or `FAILED`                                   |
| `payload.transactionId` | string | Internal transaction identifier                                                           |
| `payload.walletId`      | string | Wallet the funds were sent from                                                           |
| `payload.entityId`      | string | ID of the business that owns the wallet                                                   |
| `payload.entityType`    | string | `USER`                                                                                    |
| `payload.entry`         | string | `DEBIT`                                                                                   |
| `payload.method`        | string | Payment method (e.g. `BANK_TRANSFER`, `DEBIT_CARD`)                                       |
| `payload.amount`        | number | Net payout amount (after fees)                                                            |
| `payload.feeCharged`    | string | Fee amount charged                                                                        |
| `payload.currency`      | string | Currency code (e.g. `USD`)                                                                |
| `payload.summary`       | string | Human-readable summary                                                                    |
| `payload.description`   | string | Same as `summary`                                                                         |
| `payload.reason`        | string | Present on `FAILED` events — merchant-safe explanation. Empty string on success.          |
| `payload.timestamp`     | number | Unix timestamp in milliseconds                                                            |
| `payload.paymentLink`   | object | Payment link details. Present when the withdrawal was initiated via a payment link token. |

## Statuses

| Status               | When it fires                                                        |
| -------------------- | -------------------------------------------------------------------- |
| `PENDING`            | Immediately when the withdrawal is initiated                         |
| `PROCESSING_PAY_OUT` | ACH or RTP payout has been accepted by the network (not yet settled) |
| `SUCCESS`            | Payout has settled — funds delivered to recipient                    |
| `FAILED`             | Payout could not be completed; check `payload.reason` for details    |

Card payouts go directly from `PENDING` → `SUCCESS` (no `PROCESSING_PAY_OUT` step).

## Example: PENDING

Sent immediately when a withdrawal is initiated.

```json theme={null}
{
  "eventType": "WITHDRAWAL",
  "status": "PENDING",
  "payload": {
    "description": "Withdrawal initiated",
    "method": "BANK_TRANSFER",
    "transactionId": "7794112b-094e-443d-8454-7192aee10557",
    "walletId": "44805633-c437-4140-a312-0e626c6feb19",
    "entityId": "9b5e1e96-5796-4648-94d4-62253728291e",
    "entityType": "USER",
    "summary": "Withdrawal initiated",
    "entry": "DEBIT",
    "amount": 20.87,
    "currency": "USD",
    "timestamp": 1771347620788,
    "feeCharged": "2.04174"
  }
}
```

## Example: PROCESSING\_PAY\_OUT

Sent when an ACH or RTP payout has been submitted to and accepted by the payment network. This confirms the payment is in transit but not yet settled in the recipient's account.

```json theme={null}
{
  "eventType": "WITHDRAWAL",
  "status": "PROCESSING_PAY_OUT",
  "payload": {
    "description": "Payment sent",
    "method": "BANK_TRANSFER",
    "transactionId": "7794112b-094e-443d-8454-7192aee10557",
    "walletId": "44805633-c437-4140-a312-0e626c6feb19",
    "entityId": "9b5e1e96-5796-4648-94d4-62253728291e",
    "entityType": "USER",
    "summary": "Payment sent",
    "entry": "DEBIT",
    "amount": 20.87,
    "currency": "USD",
    "timestamp": 1771347635000,
    "feeCharged": "2.04174",
    "reason": ""
  }
}
```

## Example: SUCCESS

Sent when the payout has settled and the recipient has received the funds.

```json theme={null}
{
  "eventType": "WITHDRAWAL",
  "status": "SUCCESS",
  "payload": {
    "description": "Payment sent",
    "method": "BANK_TRANSFER",
    "transactionId": "7794112b-094e-443d-8454-7192aee10557",
    "walletId": "44805633-c437-4140-a312-0e626c6feb19",
    "entityId": "9b5e1e96-5796-4648-94d4-62253728291e",
    "entityType": "USER",
    "summary": "Payment sent",
    "entry": "DEBIT",
    "amount": 20.87,
    "currency": "USD",
    "timestamp": 1771347650000,
    "feeCharged": "2.04174",
    "reason": "",
    "paymentLink": {}
  }
}
```

## Example: FAILED

Sent when the payout could not be completed. The `reason` field contains a merchant-safe explanation.

```json theme={null}
{
  "eventType": "WITHDRAWAL",
  "status": "FAILED",
  "payload": {
    "description": "Payment failed",
    "method": "BANK_TRANSFER",
    "transactionId": "7794112b-094e-443d-8454-7192aee10557",
    "walletId": "44805633-c437-4140-a312-0e626c6feb19",
    "entityId": "9b5e1e96-5796-4648-94d4-62253728291e",
    "entityType": "USER",
    "summary": "Payment failed",
    "entry": "DEBIT",
    "amount": 20.87,
    "currency": "USD",
    "timestamp": 1771347660000,
    "feeCharged": "2.04174",
    "reason": "Recipient account not found."
  }
}
```

### Possible `reason` values on FAILED

| `reason`                                                            | Scenario                                            |
| ------------------------------------------------------------------- | --------------------------------------------------- |
| `Recipient account not found.`                                      | The recipient's bank account could not be located   |
| `Duplicate transaction detected.`                                   | A duplicate payout was submitted                    |
| `Transaction declined for compliance reasons.`                      | Payout declined due to compliance or business rules |
| `Payment could not be processed.`                                   | General processing failure                          |
| `Your payment could not be processed. Please try a different card.` | Card-specific failure                               |
| `Payment was cancelled.`                                            | Payout was cancelled                                |

## Missed a webhook?

If your system did not receive a webhook delivery, use the [Get Transaction Webhook Payload](/guides/get-transaction-webhook-payload) endpoint to fetch the current payload for any transaction by its ID.