How to: Implement Passive Crypto Pay-In Addresses (API)

This guide walks through the end-to-end integration of passive crypto pay-in addresses.

Authentication & Base URLs

The passive-address endpoints are split into two sets:

• Customer-facing (called from your end-user’s session with a Coinflow session key or wallet auth): POST /api/checkout/crypto-deposit-address/{merchantId}
• Merchant-side (called from your backend with merchant credentials, or by a Coinflow admin): /api/merchant/customer-payin-addresses/...

Sandbox base URL: https://api-sandbox.coinflow.cash Production base URL: https://api.coinflow.cash

1. List Supported Chains

Returns the chain names accepted by the create endpoint. The list is environment-aware — sandbox returns testnets (e.g. Polygon Amoy, Solana Devnet, Base Sepolia), production returns mainnets.

$
curl --location 'https://api-sandbox.coinflow.cash/api/merchant/customer-payin-addresses/supported-chains' \
>
  --header 'Authorization: {api_key}'

1
{
2
  "chains": ["Polygon Amoy", "Solana Devnet", "Base Sepolia"]
3
}

Pass any returned name verbatim as the chain field in subsequent calls. The match is case- and whitespace-insensitive.

2. Create (or Retrieve) a Passive Address

The same call is used to mint a new address and to retrieve an existing one — the response shape is identical and the operation is idempotent on (merchantId, customerId, chain).

$
curl --location --request POST \
>
  'https://api-sandbox.coinflow.cash/api/merchant/customer-payin-addresses?customerId=cust_12345' \
>
  --header 'Authorization: {api_key}' \
>
  --header 'Content-Type: application/json' \
>
  --data '{
>
    "email": "alice@example.com",
>
    "chain": "Solana Devnet"
>
  }'

1
{
2
  "depositAddress": "9XyZ...abc",
3
  "chain": "Solana Devnet",
4
  "status": "active",
5
  "createdAt": "2026-05-20T12:34:56.000Z"
6
}

Errors

3. List a Customer’s Addresses

Returns every address Coinflow has minted for a (merchant, customerId) pair, newest first, across all chains.

$
curl --location 'https://api-sandbox.coinflow.cash/api/merchant/customer-payin-addresses/cust_12345' \
>
  --header 'Authorization: {api_key}'

1
{
2
  "addresses": [
3
    {
4
      "depositAddress": "0xAbc...123",
5
      "chain": "Polygon Amoy",
6
      "status": "active",
7
      "createdAt": "2026-05-20T12:34:56.000Z"
8
    },
9
    {
10
      "depositAddress": "9XyZ...abc",
11
      "chain": "Solana Devnet",
12
      "status": "paused",
13
      "createdAt": "2026-05-15T08:00:00.000Z"
14
    }
15
  ]
16
}

Use this to populate a customer’s “Crypto Funding” page in your app.

4. Pause an Address (Deactivate)

Pauses a single address. Once paused, any deposit that subsequently lands on the address will not produce a Payment record — funds may still clear on-chain briefly during reconciliation, but Coinflow will refuse them.

$
curl --location --request POST \
>
  'https://api-sandbox.coinflow.cash/api/merchant/customer-payin-addresses/deactivate' \
>
  --header 'Authorization: {api_key}' \
>
  --header 'Content-Type: application/json' \
>
  --data '{ "depositAddress": "0xAbc...123" }'

1
{ "depositAddress": "0xAbc...123", "status": "paused" }

5. Resume an Address (Activate)

Re-activates a paused address. Subject to the same flag and cap checks as minting a new address.

$
curl --location --request POST \
>
  'https://api-sandbox.coinflow.cash/api/merchant/customer-payin-addresses/activate' \
>
  --header 'Authorization: {api_key}' \
>
  --header 'Content-Type: application/json' \
>
  --data '{ "depositAddress": "0xAbc...123" }'

1
{ "depositAddress": "0xAbc...123", "status": "active" }

6. React to Deposits via Webhook

Every successful deposit on a passive address creates a Payment record and dispatches the standard Payment Settled webhook. There is no separate “passive deposit” event — passive deposits look like any other settled payment from your webhook handler’s perspective.

1
{
2
  "eventType": "Payment Settled",
3
  "category": "Purchase",
4
  "created": "2026-05-20T12:40:00.000Z",
5
  "data": {
6
    "paymentId": "9d1f...example",
7
    "merchantId": "merch_abc",
8
    "customer": "cust_12345",
9
    "totals": {
10
      "subtotal": { "cents": 4980, "currency": "USD" },
11
      "total":    { "cents": 5000, "currency": "USD" },
12
      "merchantPaidCreditCardFees": { "cents": 20, "currency": "USD" }
13
    },
14
    "cryptoInfo": {
15
      "status": "settled",
16
      "sessionId": "ses_session_example"
17
    }
18
  }
19
}

To enable: Coinflow Admin Dashboard → Developers → Webhooks, select the latest version, and ensure Payment Settled is subscribed. See Configuring Webhooks for setup.

Best Practices

Billing

• Only active addresses incur the per-address fee. The moment you POST /deactivate an address, billing stops for it. Calling POST /activate later resumes both the address and the fee.
• Mint per chain only as needed. If a customer only ever deposits on one chain, don’t pre-mint on every supported chain — each pre-mint is another billable record.
• Ask Coinflow to set a maxActivePassiveAddresses cap if you want a hard ceiling on your active-address fee exposure. See the Active Address Cap section of the overview for details.

Per-address pricing is defined in your merchant contract — contact your Coinflow account manager for current rates.