Jump to Content

Withdrawals

Webhook events for withdrawal transaction status changes. These events apply to both fiat and crypto withdrawals.

Events

Event Name	Status	Description
`withdrawal.completed`	COMPLETED	Withdrawal successfully processed
`withdrawal.failed`	FAILED	Withdrawal transaction failed
`withdrawal.returned`	RETURNED	Withdrawal was returned by the receiving bank

withdrawal.completed

Triggered when a withdrawal transaction is successfully completed and funds have been sent.

Payload

{
  "event_name": "withdrawal.completed",
  "resource": {
    "type": "withdrawals",
    "id": "wd_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "idempotency_key": "678160c6-ca41-40ee-bfe7-35057ade157d"
  },
  "data": {
    "status": "COMPLETED",
    "customer_id": "cus_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "account_id": "BZ-ABCD-1234",
    "transaction_id": "wd_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
		"reference": "eb6305c8-5099-4b19-8e05-1a2b3c4d5e6f",
    "created_at": "2024-01-22T12:00:00.000Z",
    "modified_at": "2024-01-22T12:30:00.000Z"
  }
}

Fields

Field	Type	Description
`status`	string	Always `COMPLETED` for this event
`customer_id`	string	The customer ID who initiated the withdrawal
`account_id`	string \| null	Account ID of the customer, or `null` when unavailable
`transaction_id`	string	Unique identifier for the withdrawal transaction
`reference`	string \| null	Bank or payment network reference, when available (for example, a SWIFT UETR, Fedwire IMAD, or SPEI tracking number). The format varies by provider; may be `null`.
`created_at`	string	ISO 8601 timestamp when the withdrawal was initiated
`modified_at`	string	ISO 8601 timestamp when the withdrawal was completed

withdrawal.failed

Triggered when a withdrawal transaction fails.

Payload

{
  "event_name": "withdrawal.failed",
  "resource": {
    "type": "withdrawals",
    "id": "wd_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "idempotency_key": "678160c6-ca41-40ee-bfe7-35057ade157d"
  },
  "data": {
    "status": "FAILED",
    "customer_id": "cus_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "account_id": "BZ-ABCD-1234",
    "transaction_id": "wd_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
		"reference": "eb6305c8-5099-4b19-8e05-1a2b3c4d5e6f",
    "created_at": "2024-01-22T12:00:00.000Z",
    "modified_at": "2024-01-22T12:30:00.000Z"
  }
}

Fields

Field	Type	Description
`status`	string	Always `FAILED` for this event
`customer_id`	string	The customer ID who initiated the withdrawal
`account_id`	string \| null	Account ID of the customer, or `null` when unavailable
`transaction_id`	string	Unique identifier for the withdrawal transaction
`reference`	string \| null	Bank or payment network reference, when available (for example, a SWIFT UETR, Fedwire IMAD, or SPEI tracking number). The format varies by provider; may be `null`.
`created_at`	string	ISO 8601 timestamp when the withdrawal was initiated
`modified_at`	string	ISO 8601 timestamp when the withdrawal failed

withdrawal.returned

Triggered when a withdrawal is returned by the receiving bank. The funds are credited back to the customer's account via a corresponding deposit transaction.

Payload

{
  "event_name": "withdrawal.returned",
  "resource": {
    "type": "withdrawals",
    "id": "wd_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "idempotency_key": "678160c6-ca41-40ee-bfe7-35057ade157d"
  },
  "data": {
    "status": "RETURNED",
    "customer_id": "cus_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "account_id": "BZ-ABCD-1234",
    "transaction_id": "wd_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reference_transaction_id": "dep_xyz789",
		"reference": "eb6305c8-5099-4b19-8e05-1a2b3c4d5e6f",
    "created_at": "2024-01-22T12:00:00.000Z",
    "modified_at": "2024-01-23T10:00:00.000Z"
  }
}

Fields

Field	Type	Description
`status`	string	Always `RETURNED` for this event
`customer_id`	string	The customer ID who initiated the withdrawal
`account_id`	string \| null	Account ID of the customer, or `null` when unavailable
`transaction_id`	string	Unique identifier for the withdrawal transaction
`reference_transaction_id`	string \| null	The deposit transaction ID for the returned funds, or `null` when no linked deposit is available
`reference`	string \| null	Bank or payment network reference, when available (for example, a SWIFT UETR, Fedwire IMAD, or SPEI tracking number). The format varies by provider; may be `null`.
`created_at`	string	ISO 8601 timestamp when the withdrawal was initiated
`modified_at`	string	ISO 8601 timestamp when the withdrawal was returned

Notes

When a withdrawal is returned:

A withdrawal.returned event is sent; reference_transaction_id identifies the corresponding deposit when available
A deposit.reversed event may also be sent for the corresponding deposit record
The funds are credited back to the customer's available balance