Payout Integration

Step 1: Create Withdrawer (KYC)

Rate limit: 3 failed KYC attempts per minute.

Every withdrawer must complete verification before their first payout. KYC is one-time — unlimited payouts afterwards.

Option A: Coinflow-Managed KYC (recommended)

U.S. Users:

POST /api/withdraw/kyc
Authorization: YOUR_API_KEY
x-coinflow-auth-user-id: user123

{
  "info": {
    "email": "[email protected]",
    "firstName": "John",
    "surName": "Doe",
    "physicalAddress": "2800 N Damen Ave",
    "city": "Chicago",
    "state": "IL",
    "zip": "60625",
    "country": "US",
    "dob": "19901015",
    "ssn": "1234"
  }
}

Response:

{
  "withdrawer": {
    "_id": "672400ead654e5cdd247b33f",
    "currency": "USD",
    "email": "[email protected]",
    "verification": {"status": "approved"}
  }
}

International (Non-U.S.) Users:

POST /api/withdraw/kyc
Authorization: YOUR_API_KEY
x-coinflow-auth-user-id: user123

{
  "merchantId": "YOUR_MERCHANT_ID",
  "email": "[email protected]",
  "country": "GB"
}

CRITICAL: Handling 451 Response

If you receive HTTP 451, additional verification is needed:

{"verificationLink": "https://verify.coinflow.cash/..."}

Redirect the user to verificationLink — they'll upload a photo ID and take a selfie. Then call GET /api/withdraw to check if status is now approved.

Option B: Custom KYC Provider — Pass Documents

POST /api/withdraw/kyc-doc
Content-Type: multipart/form-data
x-coinflow-auth-session-key: YOUR_SESSION_KEY

[email protected]
country=US
idType=ID_CARD
idFront=@id_front.png
idBack=@id_back.png
merchantId=YOUR_MERCHANT_ID

Option C: Sumsub Integration (Enterprise)

Requires tri-party agreement with Sumsub and Coinflow.

POST /api/withdraw/kyc/share-token
Authorization: YOUR_API_KEY
x-coinflow-auth-user-id: user123

{
  "vendor": "sumsub",
  "shareToken": "YOUR_SHARE_TOKEN",
  "country": "US",
  "merchantId": "YOUR_MERCHANT_ID",
  "email": "[email protected]"
}

Option D: KYC Reliance (Enterprise)

Requires Coinflow Compliance approval.

POST /api/withdraw/kyc/attested
Authorization: YOUR_API_KEY
x-coinflow-auth-user-id: user123

{
  "email": "[email protected]",
  "firstName": "John",
  "surName": "Doe",
  "physicalAddress": "201 E Randolph St",
  "city": "Chicago",
  "state": "IL",
  "zip": "60601",
  "country": "US",
  "dob": "10151990",
  "ssn": "1234"
}

KYC Response Times

• KYC (individual): Average under 10 seconds
• KYB (business): Average 30 seconds (automatic), up to 24 hours for manual review
• 90% pass automatic verification

Step 2: Get Withdrawer Details

Check verification status and linked payout methods:

GET /api/withdraw
Authorization: YOUR_API_KEY
x-coinflow-auth-user-id: user123

Response:

{
  "withdrawer": {
    "_id": "672400ead654e5cdd247b33f",
    "currency": "USD",
    "email": "[email protected]",
    "verification": {"status": "approved"},
    "bankAccounts": [],
    "cards": [],
    "ibans": [],
    "pixes": []
  }
}

Step 3: Connect Payout Method

Each region has different supported methods. Connect the appropriate one.

U.S. — Bank Account (ACH)

POST /api/withdraw/account
Authorization: YOUR_API_KEY
x-coinflow-auth-user-id: user123

{
  "type": "checking",
  "alias": "Primary Checking",
  "accountNumber": "1111222233330000",
  "routingNumber": "333333334"
}

U.S. — Debit Card

Requires card tokenization first. Use CoinflowCardForm or API tokenization.

POST /api/withdraw/debit-card
Authorization: YOUR_API_KEY
x-coinflow-auth-user-id: user123

{
  "cardToken": "411111YJM5TX1111",
  "expMonth": "10",
  "expYear": "29"
}

For mobile apps (no CVV needed for debit payouts):

# 1. Get config
GET /api/checkout/mobile-tokenize-config

# 2. Tokenize card only (no CVV)
POST /api/tokenize/mobile/card-only
{"data": "4111111111111111", ...config}

# 3. Add debit card
POST /api/withdraw/debit-card
{"cardToken": "411111YJM5TX1111", "expYear": "30", "expMonth": "10"}

For web apps, use CoinflowCardOnlyInput (no CVV collection):

import {CoinflowCardOnlyInput, CardType} from '@coinflowlabs/react';

<CoinflowCardOnlyInput
  merchantId="your-merchant-id"
  ref={ref}
  cardType={CardType.VISA}
  token=""
  env="sandbox"
/>

// On submit:
const {token} = await ref.current.getToken();
// Then POST /api/withdraw/debit-card with token

U.S. — Venmo

POST /api/withdraw/venmo
Authorization: YOUR_API_KEY
x-coinflow-auth-user-id: user123

{
  "merchantId": "YOUR_MERCHANT_ID",
  "phoneNumber": "1234567890"
}

U.S. — PayPal

POST /api/withdraw/paypal
Authorization: YOUR_API_KEY
x-coinflow-auth-user-id: user123

{
  "phoneNumber": "1234567890",
  "merchantId": "YOUR_MERCHANT_ID"
}

Canada — Interac

POST /api/withdraw/interac
Authorization: YOUR_API_KEY
x-coinflow-auth-user-id: user123

{
  "phoneNumber": "1234567890",
  "merchantId": "YOUR_MERCHANT_ID"
}

EU/UK — IBAN

POST /api/withdraw/iban
Authorization: YOUR_API_KEY
x-coinflow-auth-user-id: user123

{
  "alias": "Primary Account",
  "number": "GB33BUKB20201555555555",
  "sortCode": "201234"
}

Brazil — PIX

POST /api/withdraw/pix
Authorization: YOUR_API_KEY
x-coinflow-auth-user-id: user123

{
  "pixKey": "[email protected]"
}

Response

All connect methods return the withdrawer with the new method's token:

{
  "withdrawer": {
    "bankAccounts": [{
      "token": "0dc36240-29fc-4708-81f6-bcab19e6e597",
      "alias": "Primary Checking",
      "last4": "0000",
      "routingNumber": "333333334"
    }]
  }
}

Save the token — you'll need it for initiating payouts.

Step 4: Get Quote

GET /api/withdraw/quote?token=USDC_TOKEN&amount=100&merchantId=YOUR_MERCHANT_ID&usePermit=true
Authorization: YOUR_API_KEY
x-coinflow-auth-blockchain: solana
x-coinflow-auth-user-id: user123

USDC Token addresses:

• Sandbox (Solana): 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
• Production (Solana): EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Response:

{
  "quote": {"cents": 10000, "currency": "USD"},
  "asap": {
    "fee": {"cents": 0, "currency": "USD"},
    "finalSettlement": {"cents": 10000, "currency": "USD"},
    "limit": {"cents": 1000000, "currency": "USD"},
    "expectedDeliveryDate": "in a few minutes",
    "expectedDeliveryDateISO": "2026-04-09T16:45:00.000Z"
  },
  "same_day": {
    "fee": {"cents": 50},
    "finalSettlement": {"cents": 9950},
    "limit": {"cents": 10000000}
  },
  "standard": {
    "fee": {"cents": 100},
    "finalSettlement": {"cents": 9900},
    "limit": {"cents": 10000000}
  },
  "card": {
    "fee": {"cents": 200},
    "finalSettlement": {"cents": 9800},
    "limit": {"cents": 5000000}
  }
}

Step 5: Initiate Payout

From Coinflow Wallet (Delegated)

POST /api/merchant/withdraws/payout/delegated
Authorization: YOUR_API_KEY

{
  "amount": {"cents": 10000},
  "speed": "same_day",
  "account": "0dc36240-29fc-4708-81f6-bcab19e6e597",
  "userId": "user123"
}

Response:

{
  "signature": "4Cv4nbe6fkGpdSYcqhPHXkdndeiyTa8mhFoWW5x3vroxRibAUssrbXZ5VW4vxkPedcX3xTRKu7ZpkJXWKdJBCGuq"
}

From Merchant's Own Wallet (BYO)

POST /api/merchant/withdraws/payout
Authorization: YOUR_API_KEY

{
  "blockchain": "solana",
  "amount": {"cents": 400},
  "speed": "standard",
  "wallet": "Dk462fqWGi3W6ak7ufDP4TCTfghbj4TQYukSnF4fx62J",
  "userId": "user123",
  "account": "4db3391e-3199-4c49-9897-9ad2e73390b6"
}

Self-Custodial Wallet Payout (User Signs)

Using React SDK:

import {CoinflowWithdraw} from '@coinflowlabs/react';

<CoinflowWithdraw
  wallet={{
    publicKey: new PublicKey('WALLET_PUBKEY'),
    sendTransaction: (tx) => Promise<string>,
    signMessage: (msg) => Promise<string>
  }}
  merchantId="YOUR_MERCHANT_ID"
  env="sandbox"
  blockchain="solana"
  onSuccess={(...args) => console.log('Withdraw Success', args)}
  email="[email protected]"
  amount={1}
/>

Speed Options by Region

CRITICAL: effectiveSpeed may differ from requested speed. Same-Day ACH requests above NACHA's $1,000,000 per-transaction limit are automatically downgraded to standard. Always check the effectiveSpeed field in the response.

Payout Methods by Region

Apple Pay Payouts

For pushing funds to Apple Pay-enabled cards:

const config = {
  buttonSelector: "#apple-pay-disburse",
  merchantIdentifier: "merchant.main.coinflow",
  merchantId: "YOUR_MERCHANT_ID",
  coinflowApiUrl: "https://api-sandbox.coinflow.cash",
  validateMerchantPath: "/api/checkout/apple-pay/validatemerchant",
  label: "Withdrawal",
  totalAmountCents: 1100,
  grossAmountCents: 1200,
  instantFundsOutFeeCents: 100,
  requiredRecipientContactFields: ["name", "postalAddress"],
  onSuccess: (details) => { /* handle Apple Pay token */ },
  onError: (err) => { /* handle error */ }
};

Key requirements:

• Must validate merchant from your backend
• Line items order: Total Amount → Extra Items → IFO Fee → Disbursement Amount
• Instant Funds Out fee required if supportsInstantFundsOut capability enabled
• Browser must support PaymentRequest API

Monitoring

Check Wallet Balance

GET /api/merchant/balance
Authorization: YOUR_API_KEY

View Payouts

Dashboard: sandbox.merchant.coinflow.cash/withdraws

Withdrawal History

GET /api/withdraw/history
Authorization: YOUR_API_KEY
x-coinflow-auth-user-id: user123

Marketplace Seller Payouts

For marketplace platforms where sellers need to receive payouts:

Seller Registration

POST /api/marketplace/link/seller/registration
{
  "email": "[email protected]",
  "sellerId": "seller-123",
  "country": "US",
  "redirectUrl": "https://yourapp.com/seller-dashboard"
}

Seller Login

POST /api/marketplace/link/seller/login
{"email": "[email protected]"}
// OR
{"sellerId": "seller-123"}

Sellers can withdraw from their own dashboard, or you can initiate payouts via API.

Seller Payout via API

1. Get wallet balance: GET /api/withdraw/balances
2. Add payout destination (bank, card, IBAN, PIX)
3. Get withdraw transaction: POST /api/withdraw/transaction
4. Sign and send transaction (wallet signs)

Funding Your Payout Wallet

Production

1. USDC on Solana: Contact Coinflow for wallet address
2. Wire transfer: Contact Coinflow for instructions

Sandbox

Funds are pre-loaded in sandbox for testing.

Common Pitfalls

1. Forgetting KYC before first payout — Every user needs KYC once. Call GET /api/withdraw to check status before attempting payout.

2. Not handling 451 response — Additional verification needed. Redirect user to verificationLink.

3. Using wrong USDC token in quote — Sandbox and production have different USDC token addresses.

4. Ignoring effectiveSpeed — Requested speed may be downgraded. Always use the effective speed for user-facing messaging.

5. Missing required headers — All payout endpoints need Authorization, x-coinflow-auth-user-id, and often x-coinflow-auth-blockchain.

6. Not tokenizing debit cards — PCI compliance requires tokenization. Raw card numbers must never touch your servers.

7. CVV for debit card payouts — Unlike checkout, debit card payout tokenization does NOT require CVV. Use CoinflowCardOnlyInput or POST /api/tokenize/mobile/card-only.

8. 24-hour wait for USDC withdrawals — International users withdrawing USDC to Solana wallet must wait 24 hours after verification before first withdrawal.