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.

{
  "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.

Getting Started

Authentication

Account

Wallets

Transactions

Payin

Payout

Linked Accounts

Webhooks

Event Schema

Statuses

Example: PENDING

Example: PROCESSING_PAY_OUT

Example: SUCCESS

Example: FAILED

Possible `reason` values on FAILED

Missed a webhook?

​Event Schema

​Statuses

​Example: PENDING

​Example: PROCESSING_PAY_OUT

​Example: SUCCESS

​Example: FAILED

​Possible reason values on FAILED

​Missed a webhook?

Event Schema

Statuses

Example: PENDING

Example: PROCESSING_PAY_OUT

Example: SUCCESS

Example: FAILED

Possible `reason` values on FAILED

Missed a webhook?