CheckoutPayment MethodsPayment MethodsCrypto Payments

🪪 Passive Crypto Pay-In Addresses

Mint a persistent, customer-scoped crypto deposit address that accepts variable-amount stablecoin pay-ins on supported chains. Funds sent to the address are automatically credited to the merchant as USDC.

This page is for advanced / cryptocurrency-native companies. If that’s not you, head back to the Quickstart for the standard flows.

This feature is opt-in only and must be enabled by Coinflow. Passive crypto pay-in addresses are disabled on every merchant account by default. Contact your Coinflow integrations team to have enableStableDepositAddresses turned on (and to set an optional active address cap) before you begin integration. Self-serve enablement is not available — calls to the create endpoint will return 400 Passive crypto pay-in deposit addresses are disabled for this merchant until Coinflow flips the flag for you.

Overview

A passive crypto pay-in address is a long-lived, customer-scoped deposit address that a merchant issues once and reuses for repeated stablecoin deposits. Unlike a one-time Token Payment — which mints a fresh session and address for a fixed amount on every checkout — a passive address has no preset amount, no expiry, and can collect many deposits over time.

When a customer sends supported stablecoins to the address, Coinflow:

  1. Detects the deposit via the deposit webhook.
  2. Converts it to USDC (any incoming asset on the source chain is swapped automatically).
  3. Settles to the merchant in USDC.
  4. Creates a Payment record for the deposit, which fires the standard Payment Settled webhook the same way card and one-time crypto payments do.

The address is idempotent on the tuple (merchantId, customerId, chain) — issuing the same triple a second time returns the same address. This lets merchants treat the address like a customer attribute they can display indefinitely, deposit notification after deposit notification, without managing session expiry.

When To Use This

Use passive crypto pay-in addresses when you want:

  • Recurring crypto top-ups — a customer deposits to the same address every month/week without going through a fresh checkout flow.
  • Wallet-style funding — display the address inline on a customer’s account page so they can fund their balance at will.
  • OTC / variable-amount deposits — the amount isn’t known up front, or a single customer may send several different amounts.
  • Reduced integration surface — issue once, listen on the Payment Settled webhook, no per-deposit API call required.

Use one-time Token Payments instead when the amount is fixed at checkout time (e.g. cart total) or when over/underpayment must fail the payment rather than settle.

How It Works

1

Merchant or customer requests an address

Your backend (or your customer’s checkout UI, via the SDK) calls Coinflow with the customer’s email and chain. Coinflow returns {depositAddress, chain, status, createdAt}. The same call repeated for the same (merchantId, customerId, chain) is idempotent and returns the existing record.

2

Customer sends supported stablecoins to the address

The customer sends USDC (or any supported asset on that chain — Coinflow swaps to USDC automatically) to the address. No upper or lower bound; no preset amount.

3

Coinflow detects, settles, and fires a webhook

On settlement, Coinflow creates a Payment record on the merchant and dispatches the Payment Settled webhook with the deposited USD value. The deposit is treated exactly like any other settled payment on your dashboard.

4

Repeat indefinitely

The address remains active for that customer + chain. Every subsequent deposit produces a new Payment record. No re-issuance needed.

Supported Chains

Passive deposit addresses are available on the chains Coinflow supports for stable deposit routing. As of the latest release:

NetworkMainnetTestnet
Polygon✅✅ (Amoy)
Solana✅✅ (Devnet)
Ethereum✅—
Arbitrum✅—
Base✅✅ (Sepolia)

Settlement is always in USDC, regardless of the asset the customer sends. The full token list per chain is available on the Supported Tokens and Chains page.

Address Lifecycle

Each passive address has two pieces of state:

  • status (returned to API consumers) — active or paused. This is the authoritative local intent: when an address is paused, Coinflow will refuse to create a Payment record for any deposit that lands on it, even if the deposit clears on-chain.
  • Upstream routing state — whether the upstream routing system is still directing funds to the address. Coinflow keeps the upstream routing system in sync asynchronously after every state change.

The merchant can move an individual address between active and paused, and the Coinflow admin can disable the feature merchant-wide. See Operational Behavior below.

Merchant Configuration

The following settings on cryptoPayinSettings govern the feature:

SettingTypeDescription
enabledbooleanMaster switch for all crypto pay-ins, including one-time Token Payments. Must be true for passive addresses to work.
enableStableDepositAddressesbooleanEnables the passive-address feature specifically. Toggling this off pauses every active address (see below).
maxActivePassiveAddressesnumber | undefinedCap on the number of simultaneously-active passive addresses for the merchant. Set by Coinflow on a per-merchant basis. Undefined = no cap. Paused addresses do not count.

These settings are configured by the Coinflow team — they are not self-serve. Contact your integrations contact to enable the feature, set or change the active-address cap, or adjust defaults. The values shown in API examples on this page (merchant IDs, customer IDs, deposit addresses) are examples only and are not reflective of real production values.

Active Address Cap

Coinflow may set a maxActivePassiveAddresses cap on your merchant account that limits how many addresses can be in the active state at once across all of your customers and chains. The cap is set per-merchant by the Coinflow team — there is no API or dashboard toggle to raise or lower it yourself.

When you are at the cap:

  • POST / (create) returns 400 Merchant has reached its active passive pay-in address cap (N).
  • POST /activate (resume a paused address) returns the same error.
  • Existing active addresses keep accepting deposits — only new activations are blocked.

Pausing an address with POST /deactivate immediately frees a slot. Paused addresses do not count against the cap.

If your cap is undefined, there is no merchant-side limit. Talk to your integrations contact if you need the cap raised, lowered, or removed.

Billing

Each active address is a billable line item. Coinflow charges a per-active-address fee for every (customer, chain) pair that has an active passive deposit address. A single customer with one address on Polygon and another on Solana counts as two active addresses for billing purposes — the fee scales linearly with the number of (customer, chain) combinations you keep active.

Practical implications:

  • Pause addresses you’re not actively using. A paused address is not billed; the moment you POST /activate it again, billing resumes.
  • Mint per chain only as needed. Each chain you support for a given customer is a separate active address and a separate per-address fee. If a customer only ever deposits on one chain, only mint that chain.
  • The cap protects you from runaway fees. If you have a customer base that may churn quickly, ask Coinflow to set maxActivePassiveAddresses so a spike in sign-ups doesn’t fan out into more billable addresses than you intend.

Per-address pricing is set in your merchant contract. Contact your Coinflow account manager for current rates and to confirm how active addresses count toward your invoice.

Operational Behavior

Disabling the feature mid-flight

When a Coinflow admin flips enableStableDepositAddresses from true to false, every existing active passive address for that merchant is locally paused immediately:

  1. The admin PATCH returns synchronously — even for merchants with hundreds of thousands of addresses, the request completes in milliseconds because the flip is one Mongo write.
  2. A background worker pipeline drains the upstream routing system in batches of 25 with exponential-backoff retries, so the upstream routing system eventually stops directing funds to those addresses.
  3. In the gap between local pause and upstream reconciliation, the webhook handler refuses to materialize a Payment for any deposit that lands on a locally-paused address. Funds that arrive in that window do not appear on the merchant’s books.

Re-enabling the flag does not automatically reactivate previously-paused addresses — the merchant (or admin) must POST /activate on each address they want to resume.

Hitting the active cap

If maxActivePassiveAddresses is set and the merchant is at the cap, both POST / (create) and POST /activate return:

1{
2  "statusCode": 400,
3  "message": "Merchant has reached its active passive pay-in address cap (N)"
4}

Pausing any active address frees a slot. Paused addresses do not count against the cap.

Returning an idempotent existing record

Calling POST / with a (merchantId, customerId, chain) that already has a record always returns that record, including when:

  • The record is currently paused.
  • enableStableDepositAddresses is now false.

This is intentional so customer-facing UIs can keep showing the address without breaking when the merchant toggles the flag. Only minting a new address is gated by the flag and the cap.

Next Steps