PayoutsUser Identification

Users Without Crypto Wallets

Overview

When your users don’t have crypto wallets, Coinflow uses your internal user IDs for identification. This approach works seamlessly with traditional platforms where you manage user balances internally (database, internal ledger) and initiate payouts on behalf of users.

When to Use User ID-Based Identification

Perfect For

Use internal user IDs when you manage user balances

  • Traditional gaming platforms - Internal credit/coin systems
  • Marketplaces - You track seller earnings and initiate payouts
  • Gig economy platforms - Driver/worker earnings you manage
  • Reward programs - Points or cash-back balances
  • SaaS platforms - Creator earnings, affiliate commissions
  • No Web3 infrastructure - Users have no crypto wallets

User flow: Earn balance → Request payout → Merchant disburses → Bank deposit

Use Wallet Addresses Instead

These scenarios work better with wallet identification

  • DeFi platforms - Users control on-chain balances
  • Web3 gaming - NFTs and tokens in user wallets
  • NFT marketplaces - Wallets with digital assets
  • User self-custodial - Users initiate their own withdrawals
  • DAO operations - On-chain treasury management

→ See Users With Crypto Wallets

Key Decision Factor: Who Initiates Payouts?

If you (the merchant) initiate payouts and manage balances internally, use user ID-based identification. If users control their crypto wallets and initiate withdrawals themselves, use wallet-based identification. See Understanding Payout Flows for more details.

Implementation

When using the API, pass your internal user ID in the header:

  • Header: x-coinflow-auth-user-id: YOUR_USER_ID
  • Value: Any unique, stable identifier from your system (database ID, customer ID, username, etc.)

Example API Call

$curl --request POST \
>  --url https://api-sandbox.coinflow.cash/api/withdraw/kyc \
>  --header 'Authorization: YOUR_API_KEY' \
>  --header 'x-coinflow-auth-user-id: user_12345' \
>  --header 'Content-Type: application/json' \
>  --data '{
>    "email": "user@example.com",
>    "country": "US",
>    "firstName": "Jane",
>    "lastName": "Doe"
>  }'

User ID Requirements

Must Haves

Required characteristics for user IDs

  • Unique per user - No duplicate IDs across your platform
  • Stable and permanent - Never changes for a given user
  • Consistent format - Alphanumeric strings recommended
  • Privacy-safe - Don’t use PII (emails, SSNs, names)

✅ Good examples: user_12345, cust_abc123, uid-9876

Best Practices

Recommendations for robust identification

  • Use database primary keys or UUIDs
  • Avoid sequential IDs that reveal user count
  • Store Coinflow’s withdrawer ID alongside your user ID
  • Document the ID format in your integration
  • Test with real-world ID formats early

⚠️ Avoid: emails, usernames (can change), sequential numbers

Payout Flows Using User ID Identification

Merchant Payout from Coinflow In-App Wallet

Most common flow for platforms managing user balances:

  1. Track user earnings - Store balances in your database
  2. User requests payout - Via your platform’s UI
  3. KYC verification - One-time identity check (if not done)
  4. Link bank account - User adds payout destination
  5. Merchant initiates payout - You call Coinflow API with user ID
  6. Funds disbursed - From Coinflow wallet to user’s bank

→ See Merchant Payout (Coinflow Wallet) for implementation details

Merchant Payout from Your Own Wallet (BYO)

When you want to control your own crypto wallet:

  1. Manage your crypto wallet - Hold USDC/EUROe for payouts
  2. User requests payout - Using their user ID
  3. Merchant signs transaction - Approve withdrawal from your wallet
  4. Funds disbursed - Crypto to fiat conversion, sent to user’s bank

→ See Merchant Payout (BYO Wallet)

Common Questions

Q: Can I use email addresses as user IDs? A: While possible, it’s not recommended. Emails can change, creating issues with Coinflow records. Use stable database IDs instead.

Q: What if I have multiple user ID formats across systems? A: Choose one canonical format for Coinflow integration. Map your various IDs to a single stable identifier in your integration layer.

Q: Can I change a user’s ID after they’ve completed KYC? A: No. Once a user completes KYC with a specific user ID, that ID is permanently associated with their Coinflow identity. Plan your ID strategy before going live.

Q: Do I need to store Coinflow’s withdrawer ID? A: Not required, but recommended for debugging and customer support. Store it alongside your user ID for reference.

Q: Can one user have multiple IDs? A: Each unique user ID creates a separate Coinflow identity. If you need to consolidate user accounts, contact Coinflow support for guidance.