Skip to navigation
Getting Started

Account Setup

Prerequisites every Coinflow integration depends on — sandbox merchant account, API keys, team access, settlement configuration, and (for Checkout) chargeback protection.

This page lists the foundational prerequisites that apply to every Coinflow integration. Complete these steps once before integrating any product. Each individual integration guide assumes these are done.

Foundational steps (every integration)

2

Create a sandbox API key

Generate your sandbox API key from the API Keys page. You’ll pass this in the Authorization header of every API request.

3

Invite your team

Add team members to your sandbox account so engineering, finance, and ops have the access they need.

Additional steps for Checkout integrations

If you’re integrating any Checkout products, complete these steps too:

1

Configure your settlement destination

From your merchant dashboard, choose where Coinflow delivers your collected revenue:

Want automatic settlement to your bank account? Coinflow settles to your Coinflow Wallet first, then automatically sends your balance to your bank account each day. Learn how to set it up →

If you operate your own treasury infrastructure, Coinflow can settle directly to destinations you control. See the advanced settlement guides for details.

2

Add the chargeback protection script

Add the chargeback protection script to every page of your app. This is required for fraud detection and is a prerequisite for collecting payer events.

Additional steps for Payouts from the Coinflow Wallet

If you’re paying users out from your Coinflow Wallet balance, you’ll also need to:

1

Configure your Coinflow Wallet

Set up your Coinflow Wallet from the Settings page.

2

Fund your Coinflow Wallet

Add funds to your Coinflow Wallet using the sandbox faucet. Contact support@coinflowlabs.app if you need assistance.

Authorization headers

Every Coinflow API request uses these headers. Most integration guides reference them. Bookmark this section for quick lookup: 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.

Making requests for a submerchant

If your account has submerchants, your API key can make requests on their behalf. Add the x-coinflow-submerchant-id header set to the submerchant’s merchant ID, and the request runs as that submerchant instead of your account. For marketplace sellers, the merchant ID is the sellerId you set when creating the seller.

  • The header works on every endpoint that accepts your API key, even though most endpoint pages in the API reference don’t list it.
  • The submerchant must be a child of your account, or a child of one of your submerchants. Otherwise the request fails with a 401.
  • The request is still authenticated with your API key, so your key’s IP restrictions and permissions apply, not the submerchant’s.
  • Leave the header off for requests on your own account.
  • Don’t send it to Create Submerchant. That endpoint rejects requests that include it with a 400.

For example, this fetches the account data for submerchant sellerAA:

Request
curl --location 'https://api-sandbox.coinflow.cash/api/merchant/v2' \
--header 'x-coinflow-submerchant-id: sellerAA' \
--header 'Authorization: YOUR_API_KEY' \
--header 'accept: application/json'

What’s next

Once setup is complete, jump into the integration guide for your product:

Checkout

Accept payments from your customers globally.

Payouts

Pay out your users globally.

Subscriptions

Recurring billing for subscriptions.

Marketplaces

Multi-seller payments, split payments and fees, and seller payouts.