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.