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.
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 |
PENDING → SUCCESS (no PROCESSING_PAY_OUT step).
Example: PENDING
Sent immediately when a withdrawal is initiated.
{
"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.
{
"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.
{
"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.
{
"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 endpoint to fetch the current payload for any transaction by its ID.