How To: Implement Merchant Payouts (From Coinflow Wallet)
Developers can use this documentation to implement merchant payouts (from Coinflow’s in-app wallet) to an end-user’s bank account / debit card.
This guide enables merchants to send fiat payouts to end-users’ bank accounts using Coinflow’s in-app wallet as the source of funds. All payouts are processed via API integration.
Register for a sandbox merchant account and create API keys
Configure and fund your in-app Coinflow wallet
Review the merchant payout flow before implementation
Coinflow does not provide a pre-built UI for merchant payouts - API integration required
Important Implementation Note
This flow is similar to the Merchant (BYO) Wallet Payout flow except for the endpoint used to initiate payouts. Make sure to understand your flow of funds before proceeding.
Before you begin implementing, complete these required setup steps:
Required Before Integration
You MUST complete the account setup section before you start integrating!
Register a sandbox merchant account or Login to your sandbox merchant account
Add funds to your in-app Coinflow wallet. Reach out to Coinflow team for the public key.
Quick Links:
Required Authorization Headers:
Authorization - Your API Key from the merchant dashboardx-coinflow-auth-user-id - A unique customer ID you use within your systems to identify the user withdrawing fundsx-coinflow-auth-blockchain - Should always be solanaTo 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.
Rate Limit Notice
Failed KYC attempts are limited to 3 per minute.
Choose your KYC implementation method:
Merchants who want to use Coinflow for KYC should call Register User.
U.S. Withdrawers
Endpoint: POST /api/withdraw/kyc
Non-U.S. Withdrawers
Endpoint: POST /api/withdraw/kyc
Merchants who want to pass KYC data from their existing KYC provider can call our Register User via Document endpoint.
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.
After calling our withdraw endpoints, you must call Get Withdrawer to get the latest verification status. This endpoint will tell you the user’s verification status. The get withdrawer endpoint can also be queried at any time to get more information about a withdrawer who has already completed KYC/KYB.
Endpoint: GET /api/withdraw
Withdrawers must link a payout destination so we know where to send the funds.
Want to use Coinflow’s UI for KYC and Bank Authentication?
Merchants can choose to use our UI for KYC and bank authentication, saving time by avoiding the need to build these flows and add payout destinations. You’ll only need to create the UI for displaying quotes and initiating payouts.
If you choose to use our UI, you do not need to separately implement Step 3: Add A Payout Destination as the bank auth UI also handles linking payout destinations.
If withdrawers are in the U.S. and want to receive USD, they can link their debit card or bank account.
If withdrawers reside in the EU or UK, they can link their IBAN to receive EUR or GBP.
If withdrawers reside in Brazil, they can link their PIX account to receive BRL.
Merchants may show an estimated quote of how much the user will receive after fees.
Token Values by Environment:
4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDUEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1vEndpoint: GET /api/withdraw/quote
This endpoint enables a user to submit a payout. Upon sending the request, funds from your Coinflow in-app balance will decrement, and the end-user will receive their funds in their selected payout destination.
Getting the Tokenized Account
To get the tokenized bank account or debit card, call get withdrawer and reference the token param. For example, for bank account: bankAccounts[0]['token']
Speed Options:
Pass any of the following as the speed depending on the payout method the withdrawer selects:
card - Instant debit card payoutsasap - Instant, RTP payoutsame_day - Same day ACH payoutstandard - Standard ACH payoutiban - SEPA payoutpix - PIX payoutEndpoint: POST /api/merchant/withdraws/payout/delegated
The effectiveSpeed field indicates the actual payout speed used. This may differ from the requested speed — for example, Same-Day ACH requests above NACHA’s $1,000,000 per-transaction limit are automatically downgraded to standard. Always check effectiveSpeed to confirm how the payout was processed.
Call Get Balance to get the fund balance of your in-app wallet.
When you initiate a delegated payout with waitForConfirmation=false and provide an idempotencyKey, Coinflow automatically retries the underlying Solana transaction if it is dropped from the network.
Withdraw Failure webhook so you can take appropriate action (e.g., alert your support team or retry the payout).Retries are only triggered for delegated payouts where waitForConfirmation is false and an idempotencyKey is provided. If you use waitForConfirmation=true, the API response itself will indicate success or failure.
When all retry attempts are exhausted, a Withdraw Failure webhook is sent with the following payload:
The signature in the webhook may differ from the one returned by the /payout/delegated endpoint. When Coinflow retries a dropped transaction, it rebuilds and signs a new transaction, resulting in a different signature. Always use the idempotencyKey — not the signature — to correlate webhook events with your original payout request.
When you receive a Withdraw Failure webhook for a delegated payout:
idempotencyKey — do not rely on the signature to match the one returned from the initial API call, as retries produce new signatures. You can search for the withdrawal via the Get Withdrawal endpoint using the search query parameter with your idempotency key:For more details on configuring and handling webhooks, see Withdraw Webhooks.
Now that you’ve implemented merchant payouts from your Coinflow in-app wallet, here’s what to do next:
A 451 response indicates that we need additional information to verify the withdrawer.
When you receive a 451 response, you must redirect the withdrawer to the verificationLink provided in the response body (i.e., response.verificationLink). This link takes them to our provider’s verification page, where they typically need to upload a photo ID and take a selfie.
Once the withdrawer completes the verification, send a subsequent request to the get withdrawer endpoint to confirm the verification.status == approved.
Bank authentication verifies that a user owns the bank account they’re connecting. It’s essential for preventing fraud, ensuring regulatory compliance, reducing payment failures, and protecting against chargebacks. Per our AML policies, we require it before allowing withdrawals.
You can obtain the cardToken by using our secure frontend components, which capture and tokenize card details. This token replaces sensitive card information and is then passed to your backend for further processing.
Tokenizing the card is essential for PCI compliance. It ensures that raw card data never touches your servers, helping keep your system out of PCI scope. As a PCI-compliant provider, we handle the sensitive data securely, significantly reducing your compliance burden.
If you do not have an AOC for PCI DSS, follow our Tokenize Debit Cards for Withdraws guide. If you do have an AOC, you may instead follow our Tokenize Card Data via API for Debit Card Payouts recipe.
Merchants with PCI DSS certification should be able to provide a valid Attestation of Compliance (AOC) as proof. Here is an example of an acceptable AOC for merchants.
If you’re a service provider implementing on behalf of a merchant, you must provide a valid AOC specific to service providers. This is an example of an acceptable AOC for service providers. Additionally, your AOC must be reviewed and approved by a Qualified Security Assessor (QSA).
Merchants who are ready to go live have the option to:
At this time, Coinflow does not provide a UI for the merchant payout flow. Merchants have the option of using our UI for bank authentication only.