How To: Implement User Self-Custodial Wallet Payouts

Developers can use this documentation to implement a payout from an end-user’s wallet to their bank account.

How To: Implement User Self-Custodial Wallet Payouts

Developers can use this documentation to implement a payout from an end-user’s wallet to their bank account.

User Self-Custodial Wallet Payout Guide

Overview

This guide enables end-users to withdraw funds directly from their self-custodial crypto wallet to their bank account. You can implement this using either our React SDK for a pre-built UI or our API for a custom integration.

Supported chains: Solana, Ethereum, Base, Polygon, Arbitrum, Stellar

Stellar withdrawals support both USDC and token swaps (any Stellar asset swapped to USDC via the Stellar DEX, then converted to fiat).

Prerequisites

User's Self-Custodial Wallet

End-user must have their own crypto wallet as the source of funds

Wallet Connection Capability

Ability to connect and interact with user wallets (e.g., via Web3 provider)

Transaction Signing

User wallet must be able to sign and send blockchain transactions

Choose Implementation Method

Select either React SDK (pre-built UI) or API (custom UI) implementation

Implementation Guide

Choose your preferred implementation method:

Option 1: React SDK Implementation (Recommended)

Use our pre-built React component for the fastest implementation with a complete UI.

Step 1: Install Coinflow Package

Install the Coinflow React package:

$ npm i @coinflowlabs/react

Step 2: Implement the CoinflowWithdraw Component

Add the CoinflowWithdraw component to your application:

1 <CoinflowWithdraw
2   wallet={{
3     publicKey: new PublicKey('<Wallet Public Key>'),
4     sendTransaction: (transaction: Transaction) => Promise<string>,
5     signMessage: (message: string) => Promise<string>
6   }}
7   merchantId={"YOUR_MERCHANT_ID"} // This is the merchant Id you registered an account with
8   env={"sandbox || prod"}
9   onSuccess={(...args) => console.log('Withdraw Success', args)} // Function to run when the withdraw is successful
10   blockchain={"solana"}
11   email={"user-email@email.com"} // User's email (this will be prefilled)
12 	amount={1}
13 />

Step 3: Configure Webhooks

Configure withdraw webhooks to receive notifications when users complete KYC or any withdraw events. View webhook reference

View all webhook activity from your merchant dashboard’s ‘Webhook Activity’ tab.

Option 2: API Implementation

Build a custom UI with full control over the user experience.

Step 1: Generate a Session Key

Generate a session key for the withdrawer

Endpoint: GET /api/auth/session-key

Request

1 curl --request GET \
2      --url https://api-sandbox.coinflow.cash/api/auth/session-key \
3      --header 'Authorization: YOUR_API_KEY' \
4      --header 'accept: application/json' \
5      --header 'x-coinflow-auth-blockchain: solana' \
6      --header 'x-coinflow-auth-wallet: J97rU7NN7PvAqxsEMkjSchVs2HNrUT7SNXg54HQhpqqS'

Response

1 {
2   "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiJKOTdyVTdOTjdQdkFxeHNFTWtqU2NoVnMySE5yVVQ3U05YZzU0SFFocHFxUyIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoidGVzdHRlc3QiLCJpYXQiOjE3Mzc2NjU5NDcsImV4cCI6MTczNzc1MjM0N30.orgoNHZtQP25-sq2aACzDBwv9j0t0_DS7wvEKhR0nr8"
3 }

Step 2: KYC/KYB Verification for Withdrawers

To complete a payout/withdraw, every Withdrawer must complete verification before they can proceed with a payout through Coinflow. Withdrawers only need to KYC the first time they withdraw and do not need to KYC again for any subsequent withdrawals.

Choose your KYC implementation method:

1. I want to use Coinflow for KYC

Merchants who want to use Coinflow for KYC should call Register User.

U.S. Withdrawers

Endpoint: POST /api/withdraw/kyc

Request

1 curl --location 'https://api-sandbox.coinflow.cash/api/withdraw/kyc' \
2 --header 'Authorization: YOUR_API_KEY' \
3 --header 'accept: application/json' \
4 --header 'content-type: application/json' \
5 --header 'x-coinflow-auth-user-id: usher' \
6 --data-raw '{
7   "info": {
8     "email": "usher@atl.com",
9     "firstName": "usher",
10     "surName": "raymond",
11     "physicalAddress": "2800 N Damen Ave",
12     "city": "Chicago",
13     "state": "IL",
14     "zip": "60625",
15     "country": "US",
16     "dob": "19761014",
17     "ssn": "1234"
18   }
19 }'

Response

1 {
2     "withdrawer": {
3         "_id": "672400ead654e5cdd247b33f",
4         "currency": "USD",
5         "email": "usher@atl.com",
6         "verification": {
7             "status": "approved"
8         }
9     }
10 }

Non-U.S. Withdrawers

Endpoint: POST /api/withdraw/kyc

Request

1 curl --request POST \
2 --url https://api-sandbox.coinflow.cash/api/withdraw/kyc \
3 --header 'Authorization: YOUR_API_KEY' \
4 --header 'accept: application/json' \
5 --header 'content-type: application/json' \
6 --header 'x-coinflow-auth-user-id: dwaynejohnsongb123' \
7 --data '{
8   "merchantId": "testtest",
9   "email": "dwaynejohnsongb@gmail.com",
10   "country": "GB"
11 }'

Response

1 {
2     "withdrawer": {
3         "_id": "676091072cd3ae949702b0ea",
4         "currency": "GBP",
5         "email": "dwaynejohnsongb@gmail.com",
6         "verification": {
7             "status": "approved"
8         }
9     }
10 }

2. I am using my own KYC provider and I want to pass KYC data to Coinflow

Merchants who want to pass KYC data from their existing KYC provider can call our Register User via Document endpoint.

Request

1 curl --request POST \
2 --url https://api-sandbox.coinflow.cash/api/withdraw/kyc-doc \
3 --header 'accept: application/json' \
4 --header 'content-type: multipart/form-data' \
5 --header 'x-coinflow-auth-session-key: YOUR_SESSION_KEY' \
6 --form email=dwaynejohnsonus@gmail.com \
7 --form country=US \
8 --form idType=ID_CARD \
9 --form idFront='@1128061-ID_front.png' \
10 --form idBack='@012e6a1-ID_back.png' \
11 --form merchantId=testtest

Response

1 {
2   "withdrawer": {
3     "_id": "67449b17d654e5cdd2925f1c",
4     "currency": "USD",
5     "email": "testtasha@coinflowlabs.app",
6     "verification": {
7       "status": "approved"
8     }
9   }
10 }

3. I use Sumsub as my KYC provider and I want to share KYC data with Coinflow

Merchants who want to share Sumsub data with Coinflow will need to enter a tri-party agreement with Sumsub and Coinflow. Reach out to the Coinflow team with your Sumsub client ID to get started.

Once this agreement has been signed, follow these steps:

Call Sumsub’s Generate Share Token endpoint to obtain a token.
Call our Register User Via Share Token endpoint to pass KYC data.

Request

1 curl --request POST \
2 --url https://api-sandbox.coinflow.cash/api/withdraw/kyc/share-token \
3 --header 'Authorization: YOUR_API_KEY' \
4 --header 'accept: application/json' \
5 --header 'content-type: application/json' \
6 --header 'x-coinflow-auth-user-id: user123' \
7 --data '{
8   "vendor": "sumsub",
9   "shareToken": "YOUR_SHARE_TOKEN",
10   "country": "US",
11   "merchantId": "testtest",
12   "email": "testuser@test.com"
13 }'

Response

1 {
2   "withdrawer": {
3     "_id": "67449b17d654e5cdd2925f1c",
4     "currency": "USD",
5     "email": "testtasha@coinflowlabs.app",
6     "verification": {
7       "status": "approved"
8     }
9   }
10 }

4. I have my own KYC provider and will complete KYC reliance process with Coinflow.

Merchants must receive approval from the Coinflow Compliance team regarding approval of your KYC attestation program. Once you’ve receive approval, follow these implementation steps.

Request

1 curl --request POST \
2      --url https://api-sandbox.coinflow.cash/api/withdraw/kyc/attested \
3      --header 'Authorization: YOUR_API_KEY' \
4      --header 'accept: application/json' \
5      --header 'content-type: application/json' \
6      --header 'x-coinflow-auth-user-id: user-id' \
7      --data '
8 {
9   "email": "djohnson051972@gmail.com",
10   "firstName": "Dwayne",
11   "surName": "Johnson",
12   "physicalAddress": "201 E Randolph St",
13   "city": "Chicago",
14   "state": "IL",
15   "zip": "60601",
16   "country": "US",
17   "dob": "05021972",
18   "ssn": "1234"
19 }
20 '

Response

1 {
2   "withdrawer": {
3     "_id": "685d8a89e36b426f2df64069",
4     "__v": 0,
5     "availability": {
6       "status": "Functional",
7       "reason": "Initial",
8       "editor": "system",
9       "updatedAt": "2025-06-26T17:59:37.451Z"
10     },
11     "currency": "USD",
12     "email": "djohnson051972@gmail.com",
13     "merchant": "6840bca9c7cb21ee5baaae76",
14     "originalCurrency": "USD",
15     "riskScoreOverride": false,
16     "user": true,
17     "verification": {
18       "hash": "ce749aa83c2efab20c4e1bfeca602f0674e1cf1b",
19       "vendor": "persona",
20       "reference": "ver_R6E6KrEK5rZN36Hd8d7gPaKg1cms",
21       "status": "attested"
22     },
23     "wallets": [
24       {
25         "wallet": "user-id",
26         "blockchain": "user"
27       }
28     ],
29     "watchlistExempt": "Unknown"
30   }
31 }

Step 3: Get Withdrawer Details

Call this endpoint after KYC to ensure the withdrawer’s verification.status = approved. They must be approved before they can proceed further!

Endpoint: GET /api/withdraw

Request

1 curl --request GET \
2      --url https://api-sandbox.coinflow.cash/api/withdraw \
3      --header 'accept: application/json' \
4      --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiJKOTdyVTdOTjdQdkFxeHNFTWtqU2NoVnMySE5yVVQ3U05YZzU0SFFocHFxUyIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoidGVzdHRlc3QiLCJpYXQiOjE3Mzc2NjU5NDcsImV4cCI6MTczNzc1MjM0N30.orgoNHZtQP25-sq2aACzDBwv9j0t0_DS7wvEKhR0nr8'

Response

{
  "withdrawer": {
    "_id": "6792ade0b59c605e85d20d2c",
    "__v": 0,
    "currency": "USD",
    "email": "hotstreakwithdrawer@gmail.com",
    "isBlocked": false,
    "merchant": "66311727a26b3cb28faaf97d",
    "originalCurrency": "USD",
    "riskScoreOverride": false,
    "user": true,
    "verification": {
      "hash": "2145ba11-38c3-4647-bbda-36c57a15c0e5",
      "vendor": "sumsub",
      "reference": "6792addd2d56406f20124132",
      "status": "approved"
    },
    "wallets": [
      {
        "wallet": "J97rU7NN7PvAqxsEMkjSchVs2HNrUT7SNXg54HQhpqqS",
        "blockchain": "solana"
      }
    ],
    "watchlistExempt": false,
    "bankAccounts": [],
    "cards": [],
    "ibans": [],
    "pixes": [],
    "rtpDisabled": false,
    "cardDisabled": false
  }
}

Step 4: Add Payout Destinations

Enable end-users to link their bank accounts or payment methods. Choose the appropriate endpoint based on the user’s location:

For U.S. Users - Add Bank Account

Endpoint: POST /api/withdraw/account

Request

1 curl --request POST \
2      --url https://api-sandbox.coinflow.cash/api/withdraw/account \
3      --header 'Authorization: YOUR_API_KEY' \
4      --header 'accept: application/json' \
5      --header 'content-type: application/json' \
6      --header 'x-coinflow-auth-blockchain: solana' \
7      --header 'x-coinflow-auth-wallet: J97rU7NN7PvAqxsEMkjSchVs2HNrUT7SNXg54HQhpqqS' \
8      --data '
9 {
10   "type": "checking",
11   "address": {
12     "address1": "85 E Wacker St",
13     "city": "Chicago",
14     "state": "IL",
15     "zip": "60601"
16   },
17   "routingNumber": "888889999888",
18   "accountNumber": "99999888899",
19   "alias": "Test Account"
20 }
21 '

Response

{
  "withdrawer": {
    "_id": "6792ade0b59c605e85d20d2c",
    "__v": 0,
    "currency": "USD",
    "email": "hotstreakwithdrawer@gmail.com",
    "isBlocked": false,
    "merchant": "66311727a26b3cb28faaf97d",
    "originalCurrency": "USD",
    "riskScoreOverride": false,
    "user": true,
    "verification": {
      "hash": "2145ba11-38c3-4647-bbda-36c57a15c0e5",
      "vendor": "sumsub",
      "reference": "6792addd2d56406f20124132",
      "status": "approved"
    },
    "wallets": [
      {
        "wallet": "J97rU7NN7PvAqxsEMkjSchVs2HNrUT7SNXg54HQhpqqS",
        "blockchain": "solana"
      }
    ],
    "watchlistExempt": false,
    "bankAccounts": [
      {
        "alias": "Test Account",
        "token": "e19eb25f-e9bf-45f1-9ae4-9a0b054dac2e",
        "routingNumber": "888889999888",
        "last4": "8899",
        "accountHash": "7c1c26af59e155d3d7f54a1df3946f92cb9529c4",
        "rtpEligible": false,
        "reference": "6792ae57a35ccc72ba4ebdab"
      }
    ],
    "cards": [],
    "ibans": [],
    "pixes": [],
    "rtpDisabled": false,
    "cardDisabled": false
  }
}

For U.S. Users - Add Debit Card (Push to Card)

Tokenize Debit Cards First

Before adding a debit card for payouts, you must tokenize it. Follow our Tokenize Debit Cards for Withdraws guide.

Endpoint: POST /api/withdraw/debit-card

Request

1 curl --request POST \
2      --url https://api-sandbox.coinflow.cash/api/withdraw/debit-card \
3      --header 'Authorization: <YOUR_API_KEY>' \
4      --header 'accept: application/json' \
5      --header 'content-type: application/json' \
6      --header 'x-coinflow-auth-user-id: usher' \
7      --data '
8 {
9   "cardToken": "411111YJM5TX1111",
10   "expMonth": "10",
11   "expYear": "29"
12 }
13 '

Response

411111YJM5TX1111

For U.S. Users - Add Bank Account for USD Payouts

ACH, Same Day ACH or RTP (Real Time Payments) are available.

Endpoint: POST /api/withdraw/account

Request

1 curl --location 'https://api-sandbox.coinflow.cash/api/withdraw/account' \
2 --header 'Authorization: <YOUR_API_KEY>' \
3 --header 'accept: application/json' \
4 --header 'content-type: application/json' \
5 --header 'x-coinflow-auth-user-id: usher' \
6 --data '
7 {
8   "type": "checking",
9   "alias": "Ushers Account 1",
10   "accountNumber": "1111222233330000",
11   "routingNumber": "333333334"
12 }
13 '

Response

{
    "withdrawer": {
        "_id": "672400ead654e5cdd247b33f",
        "__v": 0,
        "currency": "USD",
        "email": "usher@atl.com",
        "isBlocked": false,
        "merchant": "6723f186b2f506b29dbee63d",
        "originalCurrency": "USD",
        "user": true,
        "verification": {
            "hash": "02154e69e0f38f2b31dec3b658535fa1cc283063",
            "vendor": "persona",
            "reference": "ver_DisMcS9M3HftnJYPpFSowNEWHyjT",
            "status": "approved"
        },
        "wallets": [
            {
                "wallet": "usher",
                "blockchain": "user"
            }
        ],
        "watchlistExempt": false,
        "bankAccounts": [
          {
            "alias": "Ushers Savings 1",
            "token": "0dc36240-29fc-4708-81f6-bcab19e6e597",
            "routingNumber": "333333334",
            "last4": "0000",
            "accountHash": "cb20055931a543bcfe3183541f335f031452055a",
            "rtpEligible": false,
            "reference": "67240124b2f506b29dbef137",
            "isDeleted": false
          }
        ],
        "cards": [
            {
                "last4": "1111",
                "type": "VISA",
                "disbursementStatus": "Immediate",
                "token": "411111YJM5TX1111",
                "createdAt": "2024-10-31T22:13:56.435Z"
            }
        ],
        "ibans": [],
        "pixes": [],
        "rtpDisabled": false,
        "cardDisabled": false
    }
}

For EU Users - Add European Bank Account (IBAN)

For Euro (EUR) payouts via SEPA.

Endpoint: POST /api/withdraw/iban

Request

1 curl --location 'https://api-sandbox.coinflow.cash/api/withdraw/iban' \
2 --header 'Authorization: <YOUR_API_KEY>' \
3 --header 'accept: application/json' \
4 --header 'content-type: application/json' \
5 --header 'x-coinflow-auth-user-id: usher' \
6 --data '
7 {
8   "alias": "Ushers Account 1",
9   "number": "<Iban number>",
10 }
11 '

Response

1 {
2     "withdrawer": {
3         "_id": "672400ead654e5cdd247b33f",
4         "__v": 0,
5         "currency": "USD",
6         "email": "usher@atl.com",
7         "isBlocked": false,
8         "merchant": "6723f186b2f506b29dbee63d",
9         "originalCurrency": "USD",
10         "user": true,
11         "verification": {
12             "hash": "02154e69e0f38f2b31dec3b658535fa1cc283063",
13             "vendor": "persona",
14             "reference": "ver_DisMcS9M3HftnJYPpFSowNEWHyjT",
15             "status": "approved"
16         },
17         "wallets": [
18             {
19                 "wallet": "usher",
20                 "blockchain": "user"
21             }
22         ],
23         "watchlistExempt": false,
24         "bankAccounts": [],
25         "cards": [],
26         "ibans": [{
27             "alias": "Ushers Savings 1",
28             "token": "0dc36240-29fc-4708-81f6-bcab19e6e597",
29             "last4": "0000",
30             "accountHash": "cb20055931a543bcfe3183541f335f031452055a",
31             "reference": "67240124b2f506b29dbef137",
32             "isDeleted": false
33           }],
34         "pixes": [],
35         "rtpDisabled": false,
36         "cardDisabled": false
37     }
38 }

For UK Users - Add UK Bank Account (IBAN with Sort Code)

For GBP payouts via UK Faster Payments.

Endpoint: POST /api/withdraw/iban

Request

1 curl --location 'https://api-sandbox.coinflow.cash/api/withdraw/iban' \
2 --header 'Authorization: <YOUR_API_KEY>' \
3 --header 'accept: application/json' \
4 --header 'content-type: application/json' \
5 --header 'x-coinflow-auth-user-id: usher' \
6 --data '
7 {
8   "alias": "Ushers Account 1",
9   "number": "<Iban number>",
10   "sortCode": "<UK Sort Code>"
11 }
12 '

Response

{
    "withdrawer": {
        "_id": "672400ead654e5cdd247b33f",
        "__v": 0,
        "currency": "USD",
        "email": "usher@atl.com",
        "isBlocked": false,
        "merchant": "6723f186b2f506b29dbee63d",
        "originalCurrency": "USD",
        "user": true,
        "verification": {
            "hash": "02154e69e0f38f2b31dec3b658535fa1cc283063",
            "vendor": "persona",
            "reference": "ver_DisMcS9M3HftnJYPpFSowNEWHyjT",
            "status": "approved"
        },
        "wallets": [
            {
                "wallet": "usher",
                "blockchain": "user"
            }
        ],
        "watchlistExempt": false,
        "bankAccounts": [],
        "cards": [],
        "ibans": [{
            "alias": "Ushers Savings 1",
            "token": "0dc36240-29fc-4708-81f6-bcab19e6e597",
            "last4": "0000",
            "accountHash": "cb20055931a543bcfe3183541f335f031452055a",
            "reference": "67240124b2f506b29dbef137",
            "sortCode": "XXXXXX",
            "isDeleted": false
          }],
        "pixes": [],
        "rtpDisabled": false,
        "cardDisabled": false
    }
}

For Brazilian Users - Add PIX Account

For BRL (Brazilian Real) payouts via PIX.

Endpoint: POST /api/withdraw/pix

Request

1 curl --request POST \
2      --url https://api-sandbox.coinflow.cash/api/withdraw/pix \
3      --header 'accept: application/json' \
4      --header 'content-type: application/json' \
5      --data '{"pixKey":"1234"}'

Response

{
    "withdrawer": {
        "_id": "672400ead654e5cdd247b33f",
        "__v": 0,
        "currency": "USD",
        "email": "usher@atl.com",
        "isBlocked": false,
        "merchant": "6723f186b2f506b29dbee63d",
        "originalCurrency": "USD",
        "user": true,
        "verification": {
            "hash": "02154e69e0f38f2b31dec3b658535fa1cc283063",
            "vendor": "persona",
            "reference": "ver_DisMcS9M3HftnJYPpFSowNEWHyjT",
            "status": "approved"
        },
        "wallets": [
            {
                "wallet": "usher",
                "blockchain": "user"
            }
        ],
        "watchlistExempt": false,
        "bankAccounts": [],
        "cards": [],
        "ibans": [],
        "pixes": [ {
            "key" : "1234",
            "accountHash" : "ef501efc395b66692b1fe5aa6ad1d3f4a0af48d7",
            "token" : "7ab01310-66b1-4b13-8d80-868bd31a6f8e"
        }],
        "rtpDisabled": false,
        "cardDisabled": false
    }
}

Step 5: Get a Quote for the Withdraw

Display the quote for the withdraw by calling the Get Quote endpoint

Token Values by Environment:

Sandbox: 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
Production: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Endpoint: GET /api/withdraw/quote

1   curl --request GET \
2        --url 'https://api-sandbox.coinflow.cash/api/withdraw/quote?token=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU&amount=200&merchantId=testtest&usePermit=true' \
3        --header 'accept: application/json' \
4        --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiJKOTdyVTdOTjdQdkFxeHNFTWtqU2NoVnMySE5yVVQ3U05YZzU0SFFocHFxUyIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoidGVzdHRlc3QiLCJpYXQiOjE3Mzc2NjU5NDcsImV4cCI6MTczNzc1MjM0N30.orgoNHZtQP25-sq2aACzDBwv9j0t0_DS7wvEKhR0nr8'

1 {
2   "quote": {
3     "cents": 20000,
4     "currency": "USD"
5   },
6   "gasFees": {
7     "gasFees": {
8       "cents": 0,
9       "currency": "USD"
10     },
11     "gasFeesWei": "0"
12   },
13   "asap": {
14     "fee": {
15       "cents": 0,
16       "currency": "USD"
17     },
18     "finalSettlement": {
19       "cents": 20000,
20       "currency": "USD"
21     },
22     "limit": {
23       "cents": 1000000,
24       "currency": "USD"
25     },
26     "expectedDeliveryDate": "in a few minutes",
27     "expectedDeliveryDateISO": "2026-04-09T16:45:00.000Z"
28   },
29   "same_day": {
30     "fee": {
31       "cents": 0,
32       "currency": "USD"
33     },
34     "finalSettlement": {
35       "cents": 20000,
36       "currency": "USD"
37     },
38     "limit": {
39       "cents": 1000000,
40       "currency": "USD"
41     },
42     "expectedDeliveryDate": "in a day",
43     "expectedDeliveryDateISO": "2026-04-10T20:00:00.000Z"
44   },
45   "standard": {
46     "fee": {
47       "cents": 0,
48       "currency": "USD"
49     },
50     "finalSettlement": {
51       "cents": 20000,
52       "currency": "USD"
53     },
54     "limit": {
55       "cents": 1000000,
56       "currency": "USD"
57     },
58     "expectedDeliveryDate": "in 3 days",
59     "expectedDeliveryDateISO": "2026-04-14T20:00:00.000Z"
60   },
61   "card": {
62     "fee": {
63       "cents": 0,
64       "currency": "USD"
65     },
66     "finalSettlement": {
67       "cents": 20000,
68       "currency": "USD"
69     },
70     "limit": {
71       "cents": 5000000,
72       "currency": "USD"
73     },
74     "expectedDeliveryDate": "in a few minutes",
75     "expectedDeliveryDateISO": "2026-04-09T16:45:00.000Z"
76   }
77 }

Step 6: Create Transaction and Have User Sign

Call our Create a transaction endpoint, then have the user sign and send the transaction returned.

Getting the Account Token

When calling this endpoint, account should be the bankAccounts[0]['token'] or cards[0]['token'] value returned from calling our Get Withdrawer endpoint

Endpoint: POST /api/withdraw/transaction

Request

1 curl --request POST \
2      --url https://api-sandbox.coinflow.cash/api/withdraw/transaction \
3      --header 'accept: application/json' \
4      --header 'content-type: application/json' \
5      --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiJKOTdyVTdOTjdQdkFxeHNFTWtqU2NoVnMySE5yVVQ3U05YZzU0SFFocHFxUyIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoidGVzdHRlc3QiLCJpYXQiOjE3Mzc2NjU5NDcsImV4cCI6MTczNzc1MjM0N30.orgoNHZtQP25-sq2aACzDBwv9j0t0_DS7wvEKhR0nr8' \
6      --data '
7 {
8   "speed": "same_day",
9   "amount": 200,
10   "merchantId": "testtest",
11   "account": "e19eb25f-e9bf-45f1-9ae4-9a0b054dac2e"
12 }
13 '

Response

1 {
2   "transactions": [
3     "8vuS2C3AinK4AWdjHUtLDK7ZUiFK8QMkioNQz2KqsnoaJm2nHdPnE6xu6h3iLv6yEQ3jtBvB3vi4RdLtxCvoX2Xhs47vDk5CmSZFfaimeQgTomEfrmW5Y1vR5bwXUCde4Yojns3ECazh8XPQW2K1H58paV3AZQEV9Rv6pXSyjfRq58k9FGR4gCf44XzS4vkaj1LPjZbp8ZWhU78Gc5Q3L5gYWriRvu9h3sejaaBbtUy3dkRePrhQJnY5eSeTTShkHwnExqWC9Ki36qQfEo2TbVnDaHUYCTdKTFS8MV4rQc8LA9S1u5j2gzhoBHMWcauFd9eqRQamW33uruJNpvS6DwRU5fkGkMLFDgog8CUT8UGzrUZyWtcmgF8ogpb2n5F8drvgyKZxgh2APw2x5daSwd98rGNDKrtE3nGdJrj2GLa9oEbHWzDunF3R6E98eRKxGRnp96C1sTZSCpPrjLRkZQ5gSE1uzb8Lqy7YoT7Q6dGBYhfJea4wKdWk8f9zoiPUSFFiPTjdFarcG7yXQFE1caVJbZVXNUx1YptTa94hhguye5bsgQzDQdy8QxhVRutVRJBJZUVe2TcGWhS1pyQX6ibvZ95rPTeEyBRbu4WLvZdMZzgQXzFwxE7mL5rtw4RZPcXC1bGJSzU93wVcxfRtTeoyBDGpizxpucSXvEgwRvfMgGXk71zufD637rndZsaN4qBN75zDQhvMED7j9q2soGAK14nSqYi23o7ynUczY"
4   ]
5 }

Step 7: Sign and Send Transaction

Have the withdrawer’s wallet sign and send the transaction.

Step 8: Monitor Withdrawals (Optional)

Get withdrawal history: Get all past withdraws for a specific withdrawer
View in dashboard: Log into your admin dashboard > Withdraws to see initiated withdrawals

Next Steps

Now that you’ve implemented user self-custodial wallet payouts, here’s what to do next:

Test your integration in sandbox environment
Configure webhook notifications
Review common payout errors and troubleshooting
Test with different payout methods (bank accounts, debit cards, etc.)
Contact Coinflow team when ready to go live

User Self-Custodial Wallet Payout Guide

Overview

Supported chains: Solana, Ethereum, Base, Polygon, Arbitrum, Stellar

Stellar withdrawals support both USDC and token swaps (any Stellar asset swapped to USDC via the Stellar DEX, then converted to fiat).

Prerequisites

User's Self-Custodial Wallet

End-user must have their own crypto wallet as the source of funds

Wallet Connection Capability

Ability to connect and interact with user wallets (e.g., via Web3 provider)

Transaction Signing

User wallet must be able to sign and send blockchain transactions

Choose Implementation Method

Select either React SDK (pre-built UI) or API (custom UI) implementation

Implementation Guide

Choose your preferred implementation method:

Option 1: React SDK Implementation (Recommended)

Use our pre-built React component for the fastest implementation with a complete UI.

Step 1: Install Coinflow Package

Install the Coinflow React package:

$ npm i @coinflowlabs/react

Step 2: Implement the CoinflowWithdraw Component

Add the CoinflowWithdraw component to your application:

1 <CoinflowWithdraw
2   wallet={{
3     publicKey: new PublicKey('<Wallet Public Key>'),
4     sendTransaction: (transaction: Transaction) => Promise<string>,
5     signMessage: (message: string) => Promise<string>
6   }}
7   merchantId={"YOUR_MERCHANT_ID"} // This is the merchant Id you registered an account with
8   env={"sandbox || prod"}
9   onSuccess={(...args) => console.log('Withdraw Success', args)} // Function to run when the withdraw is successful
10   blockchain={"solana"}
11   email={"user-email@email.com"} // User's email (this will be prefilled)
12 	amount={1}
13 />

Step 3: Configure Webhooks

Configure withdraw webhooks to receive notifications when users complete KYC or any withdraw events. View webhook reference

View all webhook activity from your merchant dashboard’s ‘Webhook Activity’ tab.

Option 2: API Implementation

Build a custom UI with full control over the user experience.

Step 1: Generate a Session Key

Generate a session key for the withdrawer

Endpoint: GET /api/auth/session-key

Request

1 curl --request GET \
2      --url https://api-sandbox.coinflow.cash/api/auth/session-key \
3      --header 'Authorization: YOUR_API_KEY' \
4      --header 'accept: application/json' \
5      --header 'x-coinflow-auth-blockchain: solana' \
6      --header 'x-coinflow-auth-wallet: J97rU7NN7PvAqxsEMkjSchVs2HNrUT7SNXg54HQhpqqS'

Response

1 {
2   "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiJKOTdyVTdOTjdQdkFxeHNFTWtqU2NoVnMySE5yVVQ3U05YZzU0SFFocHFxUyIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoidGVzdHRlc3QiLCJpYXQiOjE3Mzc2NjU5NDcsImV4cCI6MTczNzc1MjM0N30.orgoNHZtQP25-sq2aACzDBwv9j0t0_DS7wvEKhR0nr8"
3 }

Step 2: KYC/KYB Verification for Withdrawers

Choose your KYC implementation method:

1. I want to use Coinflow for KYC

Merchants who want to use Coinflow for KYC should call Register User.

U.S. Withdrawers

Endpoint: POST /api/withdraw/kyc

Request

1 curl --location 'https://api-sandbox.coinflow.cash/api/withdraw/kyc' \
2 --header 'Authorization: YOUR_API_KEY' \
3 --header 'accept: application/json' \
4 --header 'content-type: application/json' \
5 --header 'x-coinflow-auth-user-id: usher' \
6 --data-raw '{
7   "info": {
8     "email": "usher@atl.com",
9     "firstName": "usher",
10     "surName": "raymond",
11     "physicalAddress": "2800 N Damen Ave",
12     "city": "Chicago",
13     "state": "IL",
14     "zip": "60625",
15     "country": "US",
16     "dob": "19761014",
17     "ssn": "1234"
18   }
19 }'

Response

1 {
2     "withdrawer": {
3         "_id": "672400ead654e5cdd247b33f",
4         "currency": "USD",
5         "email": "usher@atl.com",
6         "verification": {
7             "status": "approved"
8         }
9     }
10 }

Non-U.S. Withdrawers

Endpoint: POST /api/withdraw/kyc

Request

1 curl --request POST \
2 --url https://api-sandbox.coinflow.cash/api/withdraw/kyc \
3 --header 'Authorization: YOUR_API_KEY' \
4 --header 'accept: application/json' \
5 --header 'content-type: application/json' \
6 --header 'x-coinflow-auth-user-id: dwaynejohnsongb123' \
7 --data '{
8   "merchantId": "testtest",
9   "email": "dwaynejohnsongb@gmail.com",
10   "country": "GB"
11 }'

Response

1 {
2     "withdrawer": {
3         "_id": "676091072cd3ae949702b0ea",
4         "currency": "GBP",
5         "email": "dwaynejohnsongb@gmail.com",
6         "verification": {
7             "status": "approved"
8         }
9     }
10 }

2. I am using my own KYC provider and I want to pass KYC data to Coinflow

Merchants who want to pass KYC data from their existing KYC provider can call our Register User via Document endpoint.

Request

1 curl --request POST \
2 --url https://api-sandbox.coinflow.cash/api/withdraw/kyc-doc \
3 --header 'accept: application/json' \
4 --header 'content-type: multipart/form-data' \
5 --header 'x-coinflow-auth-session-key: YOUR_SESSION_KEY' \
6 --form email=dwaynejohnsonus@gmail.com \
7 --form country=US \
8 --form idType=ID_CARD \
9 --form idFront='@1128061-ID_front.png' \
10 --form idBack='@012e6a1-ID_back.png' \
11 --form merchantId=testtest

Response

1 {
2   "withdrawer": {
3     "_id": "67449b17d654e5cdd2925f1c",
4     "currency": "USD",
5     "email": "testtasha@coinflowlabs.app",
6     "verification": {
7       "status": "approved"
8     }
9   }
10 }

3. I use Sumsub as my KYC provider and I want to share KYC data with Coinflow

Merchants who want to share Sumsub data with Coinflow will need to enter a tri-party agreement with Sumsub and Coinflow. Reach out to the Coinflow team with your Sumsub client ID to get started.

Once this agreement has been signed, follow these steps:

Call Sumsub’s Generate Share Token endpoint to obtain a token.
Call our Register User Via Share Token endpoint to pass KYC data.

Request

1 curl --request POST \
2 --url https://api-sandbox.coinflow.cash/api/withdraw/kyc/share-token \
3 --header 'Authorization: YOUR_API_KEY' \
4 --header 'accept: application/json' \
5 --header 'content-type: application/json' \
6 --header 'x-coinflow-auth-user-id: user123' \
7 --data '{
8   "vendor": "sumsub",
9   "shareToken": "YOUR_SHARE_TOKEN",
10   "country": "US",
11   "merchantId": "testtest",
12   "email": "testuser@test.com"
13 }'

Response

1 {
2   "withdrawer": {
3     "_id": "67449b17d654e5cdd2925f1c",
4     "currency": "USD",
5     "email": "testtasha@coinflowlabs.app",
6     "verification": {
7       "status": "approved"
8     }
9   }
10 }

4. I have my own KYC provider and will complete KYC reliance process with Coinflow.

Merchants must receive approval from the Coinflow Compliance team regarding approval of your KYC attestation program. Once you’ve receive approval, follow these implementation steps.

Request

1 curl --request POST \
2      --url https://api-sandbox.coinflow.cash/api/withdraw/kyc/attested \
3      --header 'Authorization: YOUR_API_KEY' \
4      --header 'accept: application/json' \
5      --header 'content-type: application/json' \
6      --header 'x-coinflow-auth-user-id: user-id' \
7      --data '
8 {
9   "email": "djohnson051972@gmail.com",
10   "firstName": "Dwayne",
11   "surName": "Johnson",
12   "physicalAddress": "201 E Randolph St",
13   "city": "Chicago",
14   "state": "IL",
15   "zip": "60601",
16   "country": "US",
17   "dob": "05021972",
18   "ssn": "1234"
19 }
20 '

Response

1 {
2   "withdrawer": {
3     "_id": "685d8a89e36b426f2df64069",
4     "__v": 0,
5     "availability": {
6       "status": "Functional",
7       "reason": "Initial",
8       "editor": "system",
9       "updatedAt": "2025-06-26T17:59:37.451Z"
10     },
11     "currency": "USD",
12     "email": "djohnson051972@gmail.com",
13     "merchant": "6840bca9c7cb21ee5baaae76",
14     "originalCurrency": "USD",
15     "riskScoreOverride": false,
16     "user": true,
17     "verification": {
18       "hash": "ce749aa83c2efab20c4e1bfeca602f0674e1cf1b",
19       "vendor": "persona",
20       "reference": "ver_R6E6KrEK5rZN36Hd8d7gPaKg1cms",
21       "status": "attested"
22     },
23     "wallets": [
24       {
25         "wallet": "user-id",
26         "blockchain": "user"
27       }
28     ],
29     "watchlistExempt": "Unknown"
30   }
31 }

Step 3: Get Withdrawer Details

Call this endpoint after KYC to ensure the withdrawer’s verification.status = approved. They must be approved before they can proceed further!

Endpoint: GET /api/withdraw

Request

1 curl --request GET \
2      --url https://api-sandbox.coinflow.cash/api/withdraw \
3      --header 'accept: application/json' \
4      --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiJKOTdyVTdOTjdQdkFxeHNFTWtqU2NoVnMySE5yVVQ3U05YZzU0SFFocHFxUyIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoidGVzdHRlc3QiLCJpYXQiOjE3Mzc2NjU5NDcsImV4cCI6MTczNzc1MjM0N30.orgoNHZtQP25-sq2aACzDBwv9j0t0_DS7wvEKhR0nr8'

Response

{
  "withdrawer": {
    "_id": "6792ade0b59c605e85d20d2c",
    "__v": 0,
    "currency": "USD",
    "email": "hotstreakwithdrawer@gmail.com",
    "isBlocked": false,
    "merchant": "66311727a26b3cb28faaf97d",
    "originalCurrency": "USD",
    "riskScoreOverride": false,
    "user": true,
    "verification": {
      "hash": "2145ba11-38c3-4647-bbda-36c57a15c0e5",
      "vendor": "sumsub",
      "reference": "6792addd2d56406f20124132",
      "status": "approved"
    },
    "wallets": [
      {
        "wallet": "J97rU7NN7PvAqxsEMkjSchVs2HNrUT7SNXg54HQhpqqS",
        "blockchain": "solana"
      }
    ],
    "watchlistExempt": false,
    "bankAccounts": [],
    "cards": [],
    "ibans": [],
    "pixes": [],
    "rtpDisabled": false,
    "cardDisabled": false
  }
}

Step 4: Add Payout Destinations

Enable end-users to link their bank accounts or payment methods. Choose the appropriate endpoint based on the user’s location:

For U.S. Users - Add Bank Account

Endpoint: POST /api/withdraw/account

Request

1 curl --request POST \
2      --url https://api-sandbox.coinflow.cash/api/withdraw/account \
3      --header 'Authorization: YOUR_API_KEY' \
4      --header 'accept: application/json' \
5      --header 'content-type: application/json' \
6      --header 'x-coinflow-auth-blockchain: solana' \
7      --header 'x-coinflow-auth-wallet: J97rU7NN7PvAqxsEMkjSchVs2HNrUT7SNXg54HQhpqqS' \
8      --data '
9 {
10   "type": "checking",
11   "address": {
12     "address1": "85 E Wacker St",
13     "city": "Chicago",
14     "state": "IL",
15     "zip": "60601"
16   },
17   "routingNumber": "888889999888",
18   "accountNumber": "99999888899",
19   "alias": "Test Account"
20 }
21 '

Response

{
  "withdrawer": {
    "_id": "6792ade0b59c605e85d20d2c",
    "__v": 0,
    "currency": "USD",
    "email": "hotstreakwithdrawer@gmail.com",
    "isBlocked": false,
    "merchant": "66311727a26b3cb28faaf97d",
    "originalCurrency": "USD",
    "riskScoreOverride": false,
    "user": true,
    "verification": {
      "hash": "2145ba11-38c3-4647-bbda-36c57a15c0e5",
      "vendor": "sumsub",
      "reference": "6792addd2d56406f20124132",
      "status": "approved"
    },
    "wallets": [
      {
        "wallet": "J97rU7NN7PvAqxsEMkjSchVs2HNrUT7SNXg54HQhpqqS",
        "blockchain": "solana"
      }
    ],
    "watchlistExempt": false,
    "bankAccounts": [
      {
        "alias": "Test Account",
        "token": "e19eb25f-e9bf-45f1-9ae4-9a0b054dac2e",
        "routingNumber": "888889999888",
        "last4": "8899",
        "accountHash": "7c1c26af59e155d3d7f54a1df3946f92cb9529c4",
        "rtpEligible": false,
        "reference": "6792ae57a35ccc72ba4ebdab"
      }
    ],
    "cards": [],
    "ibans": [],
    "pixes": [],
    "rtpDisabled": false,
    "cardDisabled": false
  }
}

For U.S. Users - Add Debit Card (Push to Card)

Tokenize Debit Cards First

Before adding a debit card for payouts, you must tokenize it. Follow our Tokenize Debit Cards for Withdraws guide.

Endpoint: POST /api/withdraw/debit-card

Request

1 curl --request POST \
2      --url https://api-sandbox.coinflow.cash/api/withdraw/debit-card \
3      --header 'Authorization: <YOUR_API_KEY>' \
4      --header 'accept: application/json' \
5      --header 'content-type: application/json' \
6      --header 'x-coinflow-auth-user-id: usher' \
7      --data '
8 {
9   "cardToken": "411111YJM5TX1111",
10   "expMonth": "10",
11   "expYear": "29"
12 }
13 '

Response

411111YJM5TX1111

For U.S. Users - Add Bank Account for USD Payouts

ACH, Same Day ACH or RTP (Real Time Payments) are available.

Endpoint: POST /api/withdraw/account

Request

1 curl --location 'https://api-sandbox.coinflow.cash/api/withdraw/account' \
2 --header 'Authorization: <YOUR_API_KEY>' \
3 --header 'accept: application/json' \
4 --header 'content-type: application/json' \
5 --header 'x-coinflow-auth-user-id: usher' \
6 --data '
7 {
8   "type": "checking",
9   "alias": "Ushers Account 1",
10   "accountNumber": "1111222233330000",
11   "routingNumber": "333333334"
12 }
13 '

Response

{
    "withdrawer": {
        "_id": "672400ead654e5cdd247b33f",
        "__v": 0,
        "currency": "USD",
        "email": "usher@atl.com",
        "isBlocked": false,
        "merchant": "6723f186b2f506b29dbee63d",
        "originalCurrency": "USD",
        "user": true,
        "verification": {
            "hash": "02154e69e0f38f2b31dec3b658535fa1cc283063",
            "vendor": "persona",
            "reference": "ver_DisMcS9M3HftnJYPpFSowNEWHyjT",
            "status": "approved"
        },
        "wallets": [
            {
                "wallet": "usher",
                "blockchain": "user"
            }
        ],
        "watchlistExempt": false,
        "bankAccounts": [
          {
            "alias": "Ushers Savings 1",
            "token": "0dc36240-29fc-4708-81f6-bcab19e6e597",
            "routingNumber": "333333334",
            "last4": "0000",
            "accountHash": "cb20055931a543bcfe3183541f335f031452055a",
            "rtpEligible": false,
            "reference": "67240124b2f506b29dbef137",
            "isDeleted": false
          }
        ],
        "cards": [
            {
                "last4": "1111",
                "type": "VISA",
                "disbursementStatus": "Immediate",
                "token": "411111YJM5TX1111",
                "createdAt": "2024-10-31T22:13:56.435Z"
            }
        ],
        "ibans": [],
        "pixes": [],
        "rtpDisabled": false,
        "cardDisabled": false
    }
}

For EU Users - Add European Bank Account (IBAN)

For Euro (EUR) payouts via SEPA.

Endpoint: POST /api/withdraw/iban

Request

1 curl --location 'https://api-sandbox.coinflow.cash/api/withdraw/iban' \
2 --header 'Authorization: <YOUR_API_KEY>' \
3 --header 'accept: application/json' \
4 --header 'content-type: application/json' \
5 --header 'x-coinflow-auth-user-id: usher' \
6 --data '
7 {
8   "alias": "Ushers Account 1",
9   "number": "<Iban number>",
10 }
11 '

Response

1 {
2     "withdrawer": {
3         "_id": "672400ead654e5cdd247b33f",
4         "__v": 0,
5         "currency": "USD",
6         "email": "usher@atl.com",
7         "isBlocked": false,
8         "merchant": "6723f186b2f506b29dbee63d",
9         "originalCurrency": "USD",
10         "user": true,
11         "verification": {
12             "hash": "02154e69e0f38f2b31dec3b658535fa1cc283063",
13             "vendor": "persona",
14             "reference": "ver_DisMcS9M3HftnJYPpFSowNEWHyjT",
15             "status": "approved"
16         },
17         "wallets": [
18             {
19                 "wallet": "usher",
20                 "blockchain": "user"
21             }
22         ],
23         "watchlistExempt": false,
24         "bankAccounts": [],
25         "cards": [],
26         "ibans": [{
27             "alias": "Ushers Savings 1",
28             "token": "0dc36240-29fc-4708-81f6-bcab19e6e597",
29             "last4": "0000",
30             "accountHash": "cb20055931a543bcfe3183541f335f031452055a",
31             "reference": "67240124b2f506b29dbef137",
32             "isDeleted": false
33           }],
34         "pixes": [],
35         "rtpDisabled": false,
36         "cardDisabled": false
37     }
38 }

For UK Users - Add UK Bank Account (IBAN with Sort Code)

For GBP payouts via UK Faster Payments.

Endpoint: POST /api/withdraw/iban

Request

1 curl --location 'https://api-sandbox.coinflow.cash/api/withdraw/iban' \
2 --header 'Authorization: <YOUR_API_KEY>' \
3 --header 'accept: application/json' \
4 --header 'content-type: application/json' \
5 --header 'x-coinflow-auth-user-id: usher' \
6 --data '
7 {
8   "alias": "Ushers Account 1",
9   "number": "<Iban number>",
10   "sortCode": "<UK Sort Code>"
11 }
12 '

Response

{
    "withdrawer": {
        "_id": "672400ead654e5cdd247b33f",
        "__v": 0,
        "currency": "USD",
        "email": "usher@atl.com",
        "isBlocked": false,
        "merchant": "6723f186b2f506b29dbee63d",
        "originalCurrency": "USD",
        "user": true,
        "verification": {
            "hash": "02154e69e0f38f2b31dec3b658535fa1cc283063",
            "vendor": "persona",
            "reference": "ver_DisMcS9M3HftnJYPpFSowNEWHyjT",
            "status": "approved"
        },
        "wallets": [
            {
                "wallet": "usher",
                "blockchain": "user"
            }
        ],
        "watchlistExempt": false,
        "bankAccounts": [],
        "cards": [],
        "ibans": [{
            "alias": "Ushers Savings 1",
            "token": "0dc36240-29fc-4708-81f6-bcab19e6e597",
            "last4": "0000",
            "accountHash": "cb20055931a543bcfe3183541f335f031452055a",
            "reference": "67240124b2f506b29dbef137",
            "sortCode": "XXXXXX",
            "isDeleted": false
          }],
        "pixes": [],
        "rtpDisabled": false,
        "cardDisabled": false
    }
}

For Brazilian Users - Add PIX Account

For BRL (Brazilian Real) payouts via PIX.

Endpoint: POST /api/withdraw/pix

Request

1 curl --request POST \
2      --url https://api-sandbox.coinflow.cash/api/withdraw/pix \
3      --header 'accept: application/json' \
4      --header 'content-type: application/json' \
5      --data '{"pixKey":"1234"}'

Response

{
    "withdrawer": {
        "_id": "672400ead654e5cdd247b33f",
        "__v": 0,
        "currency": "USD",
        "email": "usher@atl.com",
        "isBlocked": false,
        "merchant": "6723f186b2f506b29dbee63d",
        "originalCurrency": "USD",
        "user": true,
        "verification": {
            "hash": "02154e69e0f38f2b31dec3b658535fa1cc283063",
            "vendor": "persona",
            "reference": "ver_DisMcS9M3HftnJYPpFSowNEWHyjT",
            "status": "approved"
        },
        "wallets": [
            {
                "wallet": "usher",
                "blockchain": "user"
            }
        ],
        "watchlistExempt": false,
        "bankAccounts": [],
        "cards": [],
        "ibans": [],
        "pixes": [ {
            "key" : "1234",
            "accountHash" : "ef501efc395b66692b1fe5aa6ad1d3f4a0af48d7",
            "token" : "7ab01310-66b1-4b13-8d80-868bd31a6f8e"
        }],
        "rtpDisabled": false,
        "cardDisabled": false
    }
}

Step 5: Get a Quote for the Withdraw

Display the quote for the withdraw by calling the Get Quote endpoint

Token Values by Environment:

Sandbox: 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
Production: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Endpoint: GET /api/withdraw/quote

1   curl --request GET \
2        --url 'https://api-sandbox.coinflow.cash/api/withdraw/quote?token=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU&amount=200&merchantId=testtest&usePermit=true' \
3        --header 'accept: application/json' \
4        --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiJKOTdyVTdOTjdQdkFxeHNFTWtqU2NoVnMySE5yVVQ3U05YZzU0SFFocHFxUyIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoidGVzdHRlc3QiLCJpYXQiOjE3Mzc2NjU5NDcsImV4cCI6MTczNzc1MjM0N30.orgoNHZtQP25-sq2aACzDBwv9j0t0_DS7wvEKhR0nr8'

1 {
2   "quote": {
3     "cents": 20000,
4     "currency": "USD"
5   },
6   "gasFees": {
7     "gasFees": {
8       "cents": 0,
9       "currency": "USD"
10     },
11     "gasFeesWei": "0"
12   },
13   "asap": {
14     "fee": {
15       "cents": 0,
16       "currency": "USD"
17     },
18     "finalSettlement": {
19       "cents": 20000,
20       "currency": "USD"
21     },
22     "limit": {
23       "cents": 1000000,
24       "currency": "USD"
25     },
26     "expectedDeliveryDate": "in a few minutes",
27     "expectedDeliveryDateISO": "2026-04-09T16:45:00.000Z"
28   },
29   "same_day": {
30     "fee": {
31       "cents": 0,
32       "currency": "USD"
33     },
34     "finalSettlement": {
35       "cents": 20000,
36       "currency": "USD"
37     },
38     "limit": {
39       "cents": 1000000,
40       "currency": "USD"
41     },
42     "expectedDeliveryDate": "in a day",
43     "expectedDeliveryDateISO": "2026-04-10T20:00:00.000Z"
44   },
45   "standard": {
46     "fee": {
47       "cents": 0,
48       "currency": "USD"
49     },
50     "finalSettlement": {
51       "cents": 20000,
52       "currency": "USD"
53     },
54     "limit": {
55       "cents": 1000000,
56       "currency": "USD"
57     },
58     "expectedDeliveryDate": "in 3 days",
59     "expectedDeliveryDateISO": "2026-04-14T20:00:00.000Z"
60   },
61   "card": {
62     "fee": {
63       "cents": 0,
64       "currency": "USD"
65     },
66     "finalSettlement": {
67       "cents": 20000,
68       "currency": "USD"
69     },
70     "limit": {
71       "cents": 5000000,
72       "currency": "USD"
73     },
74     "expectedDeliveryDate": "in a few minutes",
75     "expectedDeliveryDateISO": "2026-04-09T16:45:00.000Z"
76   }
77 }

Step 6: Create Transaction and Have User Sign

Call our Create a transaction endpoint, then have the user sign and send the transaction returned.

Getting the Account Token

When calling this endpoint, account should be the bankAccounts[0]['token'] or cards[0]['token'] value returned from calling our Get Withdrawer endpoint

Endpoint: POST /api/withdraw/transaction

Request

1 curl --request POST \
2      --url https://api-sandbox.coinflow.cash/api/withdraw/transaction \
3      --header 'accept: application/json' \
4      --header 'content-type: application/json' \
5      --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiJKOTdyVTdOTjdQdkFxeHNFTWtqU2NoVnMySE5yVVQ3U05YZzU0SFFocHFxUyIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoidGVzdHRlc3QiLCJpYXQiOjE3Mzc2NjU5NDcsImV4cCI6MTczNzc1MjM0N30.orgoNHZtQP25-sq2aACzDBwv9j0t0_DS7wvEKhR0nr8' \
6      --data '
7 {
8   "speed": "same_day",
9   "amount": 200,
10   "merchantId": "testtest",
11   "account": "e19eb25f-e9bf-45f1-9ae4-9a0b054dac2e"
12 }
13 '

Response

1 {
2   "transactions": [
3     "8vuS2C3AinK4AWdjHUtLDK7ZUiFK8QMkioNQz2KqsnoaJm2nHdPnE6xu6h3iLv6yEQ3jtBvB3vi4RdLtxCvoX2Xhs47vDk5CmSZFfaimeQgTomEfrmW5Y1vR5bwXUCde4Yojns3ECazh8XPQW2K1H58paV3AZQEV9Rv6pXSyjfRq58k9FGR4gCf44XzS4vkaj1LPjZbp8ZWhU78Gc5Q3L5gYWriRvu9h3sejaaBbtUy3dkRePrhQJnY5eSeTTShkHwnExqWC9Ki36qQfEo2TbVnDaHUYCTdKTFS8MV4rQc8LA9S1u5j2gzhoBHMWcauFd9eqRQamW33uruJNpvS6DwRU5fkGkMLFDgog8CUT8UGzrUZyWtcmgF8ogpb2n5F8drvgyKZxgh2APw2x5daSwd98rGNDKrtE3nGdJrj2GLa9oEbHWzDunF3R6E98eRKxGRnp96C1sTZSCpPrjLRkZQ5gSE1uzb8Lqy7YoT7Q6dGBYhfJea4wKdWk8f9zoiPUSFFiPTjdFarcG7yXQFE1caVJbZVXNUx1YptTa94hhguye5bsgQzDQdy8QxhVRutVRJBJZUVe2TcGWhS1pyQX6ibvZ95rPTeEyBRbu4WLvZdMZzgQXzFwxE7mL5rtw4RZPcXC1bGJSzU93wVcxfRtTeoyBDGpizxpucSXvEgwRvfMgGXk71zufD637rndZsaN4qBN75zDQhvMED7j9q2soGAK14nSqYi23o7ynUczY"
4   ]
5 }

Step 7: Sign and Send Transaction

Have the withdrawer’s wallet sign and send the transaction.

Step 8: Monitor Withdrawals (Optional)

Get withdrawal history: Get all past withdraws for a specific withdrawer
View in dashboard: Log into your admin dashboard > Withdraws to see initiated withdrawals

Next Steps

Now that you’ve implemented user self-custodial wallet payouts, here’s what to do next:

Test your integration in sandbox environment
Configure webhook notifications
Review common payout errors and troubleshooting
Test with different payout methods (bank accounts, debit cards, etc.)
Contact Coinflow team when ready to go live

1	<CoinflowWithdraw
2	wallet={{
3	publicKey: new PublicKey('<Wallet Public Key>'),
4	sendTransaction: (transaction: Transaction) => Promise<string>,
5	signMessage: (message: string) => Promise<string>
6	}}
7	merchantId={"YOUR_MERCHANT_ID"} // This is the merchant Id you registered an account with
8	env={"sandbox \|\| prod"}
9	onSuccess={(...args) => console.log('Withdraw Success', args)} // Function to run when the withdraw is successful
10	blockchain={"solana"}
11	email={"user-email@email.com"} // User's email (this will be prefilled)
12	amount={1}
13	/>

1	curl --request GET \
2	--url https://api-sandbox.coinflow.cash/api/auth/session-key \
3	--header 'Authorization: YOUR_API_KEY' \
4	--header 'accept: application/json' \
5	--header 'x-coinflow-auth-blockchain: solana' \
6	--header 'x-coinflow-auth-wallet: J97rU7NN7PvAqxsEMkjSchVs2HNrUT7SNXg54HQhpqqS'

1	{
2	"key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiJKOTdyVTdOTjdQdkFxeHNFTWtqU2NoVnMySE5yVVQ3U05YZzU0SFFocHFxUyIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoidGVzdHRlc3QiLCJpYXQiOjE3Mzc2NjU5NDcsImV4cCI6MTczNzc1MjM0N30.orgoNHZtQP25-sq2aACzDBwv9j0t0_DS7wvEKhR0nr8"
3	}

1	curl --location 'https://api-sandbox.coinflow.cash/api/withdraw/kyc' \
2	--header 'Authorization: YOUR_API_KEY' \
3	--header 'accept: application/json' \
4	--header 'content-type: application/json' \
5	--header 'x-coinflow-auth-user-id: usher' \
6	--data-raw '{
7	"info": {
8	"email": "usher@atl.com",
9	"firstName": "usher",
10	"surName": "raymond",
11	"physicalAddress": "2800 N Damen Ave",
12	"city": "Chicago",
13	"state": "IL",
14	"zip": "60625",
15	"country": "US",
16	"dob": "19761014",
17	"ssn": "1234"
18	}
19	}'

1	{
2	"withdrawer": {
3	"_id": "672400ead654e5cdd247b33f",
4	"currency": "USD",
5	"email": "usher@atl.com",
6	"verification": {
7	"status": "approved"
8	}
9	}
10	}

1	curl --request POST \
2	--url https://api-sandbox.coinflow.cash/api/withdraw/kyc \
3	--header 'Authorization: YOUR_API_KEY' \
4	--header 'accept: application/json' \
5	--header 'content-type: application/json' \
6	--header 'x-coinflow-auth-user-id: dwaynejohnsongb123' \
7	--data '{
8	"merchantId": "testtest",
9	"email": "dwaynejohnsongb@gmail.com",
10	"country": "GB"
11	}'

1	{
2	"withdrawer": {
3	"_id": "676091072cd3ae949702b0ea",
4	"currency": "GBP",
5	"email": "dwaynejohnsongb@gmail.com",
6	"verification": {
7	"status": "approved"
8	}
9	}
10	}

1	{
2	"withdrawer": {
3	"_id": "67449b17d654e5cdd2925f1c",
4	"currency": "USD",
5	"email": "testtasha@coinflowlabs.app",
6	"verification": {
7	"status": "approved"
8	}
9	}
10	}

1	{
2	"withdrawer": {
3	"_id": "685d8a89e36b426f2df64069",
4	"__v": 0,
5	"availability": {
6	"status": "Functional",
7	"reason": "Initial",
8	"editor": "system",
9	"updatedAt": "2025-06-26T17:59:37.451Z"
10	},
11	"currency": "USD",
12	"email": "djohnson051972@gmail.com",
13	"merchant": "6840bca9c7cb21ee5baaae76",
14	"originalCurrency": "USD",
15	"riskScoreOverride": false,
16	"user": true,
17	"verification": {
18	"hash": "ce749aa83c2efab20c4e1bfeca602f0674e1cf1b",
19	"vendor": "persona",
20	"reference": "ver_R6E6KrEK5rZN36Hd8d7gPaKg1cms",
21	"status": "attested"
22	},
23	"wallets": [
24	{
25	"wallet": "user-id",
26	"blockchain": "user"
27	}
28	],
29	"watchlistExempt": "Unknown"
30	}
31	}

1	curl --request POST \
2	--url https://api-sandbox.coinflow.cash/api/withdraw/debit-card \
3	--header 'Authorization: <YOUR_API_KEY>' \
4	--header 'accept: application/json' \
5	--header 'content-type: application/json' \
6	--header 'x-coinflow-auth-user-id: usher' \
7	--data '
8	{
9	"cardToken": "411111YJM5TX1111",
10	"expMonth": "10",
11	"expYear": "29"
12	}
13	'

1	curl --request GET \
2	--url 'https://api-sandbox.coinflow.cash/api/withdraw/quote?token=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU&amount=200&merchantId=testtest&usePermit=true' \
3	--header 'accept: application/json' \
4	--header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiJKOTdyVTdOTjdQdkFxeHNFTWtqU2NoVnMySE5yVVQ3U05YZzU0SFFocHFxUyIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoidGVzdHRlc3QiLCJpYXQiOjE3Mzc2NjU5NDcsImV4cCI6MTczNzc1MjM0N30.orgoNHZtQP25-sq2aACzDBwv9j0t0_DS7wvEKhR0nr8'

1	{
2	"quote": {
3	"cents": 20000,
4	"currency": "USD"
5	},
6	"gasFees": {
7	"gasFees": {
8	"cents": 0,
9	"currency": "USD"
10	},
11	"gasFeesWei": "0"
12	},
13	"asap": {
14	"fee": {
15	"cents": 0,
16	"currency": "USD"
17	},
18	"finalSettlement": {
19	"cents": 20000,
20	"currency": "USD"
21	},
22	"limit": {
23	"cents": 1000000,
24	"currency": "USD"
25	},
26	"expectedDeliveryDate": "in a few minutes",
27	"expectedDeliveryDateISO": "2026-04-09T16:45:00.000Z"
28	},
29	"same_day": {
30	"fee": {
31	"cents": 0,
32	"currency": "USD"
33	},
34	"finalSettlement": {
35	"cents": 20000,
36	"currency": "USD"
37	},
38	"limit": {
39	"cents": 1000000,
40	"currency": "USD"
41	},
42	"expectedDeliveryDate": "in a day",
43	"expectedDeliveryDateISO": "2026-04-10T20:00:00.000Z"
44	},
45	"standard": {
46	"fee": {
47	"cents": 0,
48	"currency": "USD"
49	},
50	"finalSettlement": {
51	"cents": 20000,
52	"currency": "USD"
53	},
54	"limit": {
55	"cents": 1000000,
56	"currency": "USD"
57	},
58	"expectedDeliveryDate": "in 3 days",
59	"expectedDeliveryDateISO": "2026-04-14T20:00:00.000Z"
60	},
61	"card": {
62	"fee": {
63	"cents": 0,
64	"currency": "USD"
65	},
66	"finalSettlement": {
67	"cents": 20000,
68	"currency": "USD"
69	},
70	"limit": {
71	"cents": 5000000,
72	"currency": "USD"
73	},
74	"expectedDeliveryDate": "in a few minutes",
75	"expectedDeliveryDateISO": "2026-04-09T16:45:00.000Z"
76	}
77	}

1	{
2	"transactions": [
3	"8vuS2C3AinK4AWdjHUtLDK7ZUiFK8QMkioNQz2KqsnoaJm2nHdPnE6xu6h3iLv6yEQ3jtBvB3vi4RdLtxCvoX2Xhs47vDk5CmSZFfaimeQgTomEfrmW5Y1vR5bwXUCde4Yojns3ECazh8XPQW2K1H58paV3AZQEV9Rv6pXSyjfRq58k9FGR4gCf44XzS4vkaj1LPjZbp8ZWhU78Gc5Q3L5gYWriRvu9h3sejaaBbtUy3dkRePrhQJnY5eSeTTShkHwnExqWC9Ki36qQfEo2TbVnDaHUYCTdKTFS8MV4rQc8LA9S1u5j2gzhoBHMWcauFd9eqRQamW33uruJNpvS6DwRU5fkGkMLFDgog8CUT8UGzrUZyWtcmgF8ogpb2n5F8drvgyKZxgh2APw2x5daSwd98rGNDKrtE3nGdJrj2GLa9oEbHWzDunF3R6E98eRKxGRnp96C1sTZSCpPrjLRkZQ5gSE1uzb8Lqy7YoT7Q6dGBYhfJea4wKdWk8f9zoiPUSFFiPTjdFarcG7yXQFE1caVJbZVXNUx1YptTa94hhguye5bsgQzDQdy8QxhVRutVRJBJZUVe2TcGWhS1pyQX6ibvZ95rPTeEyBRbu4WLvZdMZzgQXzFwxE7mL5rtw4RZPcXC1bGJSzU93wVcxfRtTeoyBDGpizxpucSXvEgwRvfMgGXk71zufD637rndZsaN4qBN75zDQhvMED7j9q2soGAK14nSqYi23o7ynUczY"
4	]
5	}