Merchant Payouts from Your Coinflow wallet
This is the most common payout flow for platforms that hold a user balance and disburse to that user when they request a withdrawal — gaming platforms, marketplaces, gig economy apps, reward programs, SaaS creator earnings, and similar.
Your backend tracks the balance. When a user requests a payout, you call Coinflow to (1) verify the user’s identity, (2) save where they want their money sent, and (3) initiate the payout. Funds come out of your Coinflow wallet.
Platforms where the merchant tracks user balances and initiates payouts on the user’s behalf.
Your Coinflow wallet — the same balance that receives proceeds from Coinflow Checkout.
US bank account, US debit card (push-to-card), IBAN (EUR/GBP), PIX (BRL).
API-driven. Coinflow optionally provides a pre-built Bank Authentication UI that handles KYC + linking a destination.
How the flow works
Prerequisites
Complete account setup first
This integration assumes you’ve completed the Account Setup prerequisites — sandbox merchant account, API key, team access, and any product-specific configuration (settlement location, chargeback protection, or wallet funding).
Before sending real payouts, you’ll need:
- A merchant account (register on sandbox) and an API key.
- A funded Coinflow wallet. In sandbox, contact the Coinflow team for test funds. In production, your balance fills from Coinflow Checkout proceeds.
- (Optional) Webhook endpoint configured to receive payout status updates — see Withdraw Webhooks.
Authorization Headers:
Authorization— Your API key from the merchant dashboard.x-coinflow-auth-user-id— A unique customer ID from your own systems identifying the payer or payee.x-coinflow-auth-session-key— A JWT that authorizes the payer. Valid for 24 hours; refresh after expiry.
Implementation
Step 1: Verify the withdrawer (KYC/KYB)
Every user must complete identity verification before their first payout. Once verified, the same user can be paid out repeatedly with no re-verification.
Choose the path that matches how you handle identity today:
Coinflow handles KYC (most common)
Upload identity documents
Share a token from an existing identity provider
Attest to your own KYC (KYC Reliance)
Pass the user’s details to Coinflow and we run identity verification end-to-end.
US withdrawers require full SSN, address, and date of birth.
Non-US withdrawers require email and country only at this step. The user completes identity verification through a hosted link returned in the response.
451 response? Coinflow needs additional info from the user. Redirect them to the verificationLink in the response body — they’ll upload a photo ID and complete a selfie verification. After they finish, poll GET /withdraw until verification.status === "approved".
Step 2: Check the withdrawer’s verification status
After KYC, fetch the withdrawer record to confirm verification status before adding a payout destination. You can call this at any time to look up a withdrawer.
Step 3: Add a payout destination
Save the place the user wants to receive funds. Available destinations depend on the country they verified under.
Want to skip building destination UI? Coinflow’s Bank Authentication UI embeds the entire KYC + destination flow in your app. If you use it, you can skip Step 1 and Step 3 — you’ll only need the quote and payout endpoints below.
US bank account
US debit card (push-to-card)
IBAN (EUR / GBP)
PIX (BRL)
Step 4: Get a quote
Before initiating, fetch a quote so you can show the user fees, expected delivery time, and how much they’ll actually receive. The response includes every speed option available for their destination — card (instant), asap (RTP), same_day (Same-Day ACH), and standard (Standard ACH).
Step 5: Initiate the payout
Submit the payout. Your Coinflow wallet is debited; the user’s funds are sent to their selected destination.
effectiveSpeed may differ from the speed you requested. Same-Day ACH requests above NACHA’s per-transaction limit ($1,000,000) are automatically downgraded to standard. Always read effectiveSpeed from the response to confirm how the payout was actually processed.
Step 6: Monitor
Track payouts through whichever channel suits your operations:
- Withdraw webhooks — recommended. Receive real-time status changes (initiated, settled, failed, returned).
- Merchant dashboard — visual interface for support and ops teams.
- Get Balance — check your remaining Coinflow wallet programmatically.
Advanced
Funding your Coinflow wallet
In sandbox, contact the Coinflow team to provision test funds — there’s no production money involved.
In production, your Coinflow wallet fills automatically from Coinflow Checkout proceeds. If you need to top up directly (e.g., to seed payouts before you’ve taken any pay-ins), contact the Coinflow team for wire instructions.
No pre-built UI for the full payout flow
Coinflow does not currently provide a drop-in UI for merchant-initiated payouts — this integration is API-driven. You can use Coinflow’s Bank Authentication UI for the KYC and destination-linking portion only, then call the quote and payout endpoints from your own UI for the rest of the flow.
FAQ
What does a 451 verification response mean?
Coinflow needs additional information from the withdrawer (commonly a photo ID and selfie). The response body includes a verificationLink — redirect the user there. Once they complete the steps, poll GET /withdraw and check verification.status === "approved".
Why is bank authentication required?
Bank authentication confirms the user owns the account they’re connecting. Per AML policy, Coinflow requires it before any withdrawal. It also prevents fraud, reduces failed payments, and protects against chargebacks.
How do I tokenize a debit card for push-to-card?
Raw card numbers must never reach your servers (PCI compliance). Coinflow provides PCI-compliant tokenization through hosted iframe components.
- Without a PCI DSS AOC: use Tokenize Debit Cards for Withdraws.
- With a valid AOC: use Tokenize Card Data via API for Debit Card Payouts.
How do I know if I have a valid PCI DSS AOC?
Merchants need a current Attestation of Compliance (AOC) from a Qualified Security Assessor. Sample formats: merchant AOC, service-provider AOC. If you’re implementing on behalf of a merchant, you need a service-provider AOC.