Developer ResourcesWebhooks

Withdraw Webhooks

Developers can use this documentation to listen to webhooks associatied with KYC/B and Withdrawals.

This page is for advanced / cryptocurrency-native companies. If that’s not you, head back to the Quickstart for the standard flows.

Webhooks may be sent more than once—add deduplication logic to prevent duplicate events.

✅ Event Types

Event TypeDescription
KYC CreatedKYC process has started
KYC SuccessKYC passed
KYC FailureKYC failed
Withdraw PendingWithdrawal has been initiated
Withdraw SuccessWithdrawal submitted to the bank
Withdraw FailureWithdrawal failed
Withdraw UnclaimedPayPal/Venmo payout is awaiting the recipient to claim it
Payout Account LinkedA new PayPal/Venmo payout destination was created for a withdrawer
Interac PINInterac payout received its Interac code

Sample Webhook Payloads

The "blockchain": "user" field in the payloads below is the default value identifying the merchant’s own user records — it isn’t a network reference.

🧾 KYC Events

KYC Created
1{
2  "eventType": "KYC Created",
3  "category": "KYC",
4  "created": "2025-04-08T16:26:32.109Z",
5  "data": {
6    "wallet": "test-withdrawer-f",
7    "blockchain": "user",
8    "email": "testwithdrawer-f@gmail.com"
9  }
10}
KYC Success
1{
2  "eventType": "KYC Success",
3  "category": "KYC",
4  "created": "2025-04-08T16:26:33.520Z",
5  "data": {
6    "wallet": "test-withdrawer-f",
7    "blockchain": "user",
8    "email": "testwithdrawer-f@gmail.com"
9  }
10}
KYC Failure
1{
2  "eventType": "KYC Failure",
3  "category": "KYC",
4  "created": "2025-04-09T20:45:24.515Z",
5  "data": {
6    "wallet": "test-f",
7    "blockchain": "user",
8    "email": "test-f@gmail.com "
9  }
10}

💸 Withdraw Events

Withdraw Pending
1{
2  "eventType": "Withdraw Pending",
3  "category": "Withdraw",
4  "created": "2025-04-08T17:05:56.718Z",
5  "data": {
6    "wallet": "user123",
7    "blockchain": "user",
8    "signature": "5nQq5iVkoEc1gomDENhVNkYVXA61kzjsXKiZiAm6iq36wX3auEdrN1jZBAE5mggZWRbTvfRw5AAiVJ2ah6TaRMXS",
9    "userFees": { "cents": 200, "currency": "USD" },
10    "userGasFees": { "cents": 0, "currency": "USD" },
11    "merchantGasFees": { "cents": 2, "currency": "USD" },
12    "total": { "cents": 202, "currency": "USD" },
13    "currency": "USD",
14    "merchantId": "testtest",
15    "idempotencyKey": "merchant-withdrawal-12345"
16  }
17}
Withdraw Success
1{
2  "eventType": "Withdraw Success",
3  "category": "Withdraw",
4  "created": "2025-04-08T17:06:05.177Z",
5  "data": {
6    "wallet": "user123",
7    "blockchain": "user",
8    "signature": "5nQq5iVkoEc1gomDENhVNkYVXA61kzjsXKiZiAm6iq36wX3auEdrN1jZBAE5mggZWRbTvfRw5AAiVJ2ah6TaRMXS",
9    "userFees": { "cents": 200, "currency": "USD" },
10    "userGasFees": { "cents": 0, "currency": "USD" },
11    "merchantGasFees": { "cents": 2, "currency": "USD" },
12    "total": { "cents": 202, "currency": "USD" },
13    "currency": "USD",
14    "merchantId": "testtest",
15    "idempotencyKey": "merchant-withdrawal-12345"
16  }
17}
Withdraw Failure
1{
2  "eventType": "Withdraw Failure",
3  "category": "Withdraw",
4  "created": "2025-04-08T17:07:05.177Z",
5  "data": {
6    "wallet": "user123",
7    "blockchain": "user",
8    "signature": "5nQq5iVkoEc1gomDENhVNkYVXA61kzjsXKiZiAm6iq36wX3auEdrN1jZBAE5mggZWRbTvfRw5AAiVJ2ah6TaRMXS",
9    "userFees": { "cents": 200, "currency": "USD" },
10    "userGasFees": { "cents": 0, "currency": "USD" },
11    "merchantGasFees": { "cents": 2, "currency": "USD" },
12    "total": { "cents": 202, "currency": "USD" },
13    "currency": "USD",
14    "merchantId": "testtest",
15    "idempotencyKey": "merchant-withdrawal-12345"
16  }
17}
Withdraw Unclaimed
1{
2  "eventType": "Withdraw Unclaimed",
3  "category": "Withdraw",
4  "created": "2025-04-08T17:08:05.177Z",
5  "data": {
6    "wallet": "user123",
7    "blockchain": "user",
8    "signature": "5nQq5iVkoEc1gomDENhVNkYVXA61kzjsXKiZiAm6iq36wX3auEdrN1jZBAE5mggZWRbTvfRw5AAiVJ2ah6TaRMXS",
9    "userFees": { "cents": 200, "currency": "USD" },
10    "userGasFees": { "cents": 0, "currency": "USD" },
11    "merchantGasFees": { "cents": 2, "currency": "USD" },
12    "total": { "cents": 202, "currency": "USD" },
13    "currency": "USD",
14    "merchantId": "testtest",
15    "idempotencyKey": "merchant-withdrawal-12345"
16  }
17}

A Withdraw Unclaimed event fires when a PayPal or Venmo payout is delivered to a recipient who has not yet accepted the funds (for example, an email or phone number with no PayPal/Venmo account behind it). Coinflow automatically cancels payouts that remain unclaimed after 24 hours, at which point a Withdraw Failure event follows.

🔗 Payout Account Linked Event

A Payout Account Linked event fires when a withdrawer creates a new PayPal or Venmo payout destination.

The event fires only when a new payout destination token is minted. Re-linking an account that is already on file — including one the withdrawer previously removed — returns the original token and does not fire the event.

Payout Account Linked
1{
2  "eventType": "Payout Account Linked",
3  "category": "Withdraw",
4  "created": "2025-04-08T17:09:05.177Z",
5  "data": {
6    "token": "00000000-0000-4000-8000-0000000000aa",
7    "userId": "user123",
8    "merchantId": "testtest",
9    "paymentMethod": "PayPal",
10    "payerId": "EXAMPLEPAYER1",
11    "email": "recipient@example.com"
12  }
13}
FieldTypeDescription
tokenstringThe Coinflow token for the payout destination, matching the token the link endpoints return
userIdstringThe id of the withdrawer the payout destination belongs to. If you use the x-coinflow-user-id header, this is that value
merchantIdstringYour merchant id
paymentMethodstringPayPal or Venmo
payerIdstringOptional. The payer’s stable PayPal account id
emailstringOptional. The email the account was linked with
phoneNumberstringOptional. The phone number the account was linked with
countryCodestringOptional. The dialing country code that accompanies phoneNumber

payerId is only present for PayPal accounts linked through Log in with PayPal, and only when PayPal returns one. PayPal accounts added manually and all Venmo accounts carry email or phoneNumber instead. An account is always identified by at least one of payerId, email, or phoneNumber — never assume payerId is there.

The token, userId, payerId, and contact values above are examples only and are not reflective of real production values.

🔐 Interac PIN Event

This event fires when an Interac payout receives its Interac code (PIN), so you can display the code to the recipient without polling.

FieldTypeDescription
withdrawerIdstringThe id of the withdrawer (user or business) the payout belongs to
transferIdstringThe provider transfer id for the Interac payout
pinstringThe Interac code (PIN) the recipient uses to claim the payout

Advanced: Stablecoin Deposit Webhooks

The events below apply only to merchants accepting stablecoin deposits. If you’re integrating standard payouts to bank accounts, you can skip this section.

Event TypeDescription
CryptoDepositFundsReceivedFunds received for stablecoin deposit session

Stablecoin Deposit Events

CryptoDepositFundsReceived
1{
2  "eventType": "CryptoDepositFundsReceived",
3  "category": "CryptoDeposit",
4  "created": "2024-01-01T00:00:00.000Z",
5  "data": {
6    "sessionId": "session-123",
7    "depositAddress": "deposit-address-here",
8    "blockchainChainId": "solana",
9    "blockchainName": "Solana",
10    "tokenSymbol": "USDC",
11    "user": "user-456",
12    "amount": {
13      "cents": 10000,
14      "currency": "USD"
15    },
16    "merchantId": "merchant-789",
17    "transactionHash": "tx-hash-here",
18    "receivedAt": "2024-01-01T00:00:00.000Z"
19  }
20}

Description

This webhook is sent when a stablecoin deposit transaction has been successfully processed and funds have been received. It includes details about the deposit address, settlement network, token details, and the amount received.

The amount field contains the received amount in cents with USD currency.

Use Cases

  • Confirming successful stablecoin deposits
  • Updating user balances
  • Triggering downstream processes like withdrawals
  • Recording transaction history