Crypto collection

Collect stablecoin (USDC, USDT) from customers where your account and environment support it. You can use the same hosted checkout pattern as card and mobile money, or drive everything from your backend with deposit quotes when you need payment instructions in JSON.

Pricing, expected on-chain amounts, and settlement are handled by the platform; you still reconcile with your reference, transaction references, and webhooks.

Supported tokens and networks (checkout)

Checkout crypto uses token (e.g. USDC, USDT) and network (a stable asset code returned in crypto_available_networks). The table below is the full product matrix; your environment may still hide options until they are configured.

Use the network string exactly as returned in crypto_available_networks[].network when calling select-method—do not guess abbreviations (for example Ethereum is USDC_ETHEREUM / USDT_ETHEREUM, not ETH).

In production, still prefer live discovery: GET /api/v1/client/currencies plus the crypto_available_tokens / crypto_available_networks payloads for the session, so you never drift from what is enabled for that checkout.

Supported assets (quotes)

For client quote flows (POST /api/v1/client/quotes), stablecoin corridors and payment_network / payment_address rules are documented on Quotes and REST resource. Typical funding tokens are USDC and USDT; network codes there follow the quote/OpenAPI contract (may differ from checkout network strings—always take values from the create/accept response for that flow).

Hosted checkout

Initialize payment

Use the same endpoint as other collection types:

POST /api/v1/client/checkout/initialize

Authentication

Signed requests as in Authentication.

Request body (example)

Use fiat currency and amount for the checkout total (commonly USD for crypto checkout). The flow converts that to a stablecoin amount after the customer picks token and network.

To only offer crypto on hosted checkout, pass payment_methods:

{  "email": "customer@example.com",  "first_name": "Ada",  "last_name": "Lovelace",  "amount": "100.00",  "currency": "USD",  "reference": "ORDER-CRYPTO-001",  "redirectUrl": "https://your-site.com/payment/complete",  "description": "Order ORDER-CRYPTO-001",  "checkout_display_name": "Your store name",  "payment_methods": ["CRYPTO"]}

You can combine methods, e.g. ["CRYPTO", "CARD"], so the customer can choose at checkout.

Field names and required fields follow the same rules as card collection — Initialize. Amounts are decimal strings, not floats.

Success response (201 / 200 — shape)

{  "success": true,  "message": "Transaction Initialized Successfully",  "data": {    "access_code": "AbCdEfGhIjKlMnOpQrStUv",    "checkout_link": "https://checkout.example.com/checkout/AbCdEfGhIjKlMnOpQrStUv",    "transactionRef": "TXN-REF-456789",    "reference": "ORDER-CRYPTO-001",    "redirectUrl": "https://your-site.com/payment/complete"  }}

Send the customer to data.checkout_link unless you implement the select-method steps yourself (see below). Store transactionRef with your reference for support and verification.

Crypto must be enabled for the payer and configured for your environment; otherwise initialize or later steps may return an error—treat messages as authoritative and confirm with support if onboarding is incomplete.

Choosing crypto on the checkout session (hosted or custom UI)

After initialize, the browser or your own front end drives the hosted checkout session using the access_code from the URL. These session calls do not use your business HMAC headers because the checkout access code acts as the session secret.

Endpoint (each step): POST /api/v1/checkout/:access_code/select-method

Step 1 — Choose crypto rail

Request

{  "method": "CRYPTO"}

Response (200) — pick a token next

{  "success": true,  "message": "Select a token",  "data": {    "selected_payment_method": "CRYPTO",    "crypto_available_tokens": [      { "token": "USDC", "label": "USD Coin" },      { "token": "USDT", "label": "Tether USD" }    ]  }}

If only one token is configured, the server may skip this step and proceed automatically.

Step 2 — Choose token

Request

{  "method": "CRYPTO",  "token": "USDC"}

Response (200) — pick a network from the list

{  "success": true,  "message": "Select a network",  "data": {    "selected_payment_method": "CRYPTO",    "crypto_token": "USDC",    "crypto_available_networks": [      { "network": "USDC_POLYGON", "network_label": "Polygon" },      { "network": "USDC_ETHEREUM", "network_label": "Ethereum" },      { "network": "USDC_BSC", "network_label": "BNB Smart Chain" },      { "network": "USDC_ARBITRUM", "network_label": "Arbitrum One" },      { "network": "USDC_TRON", "network_label": "Tron" }    ]  }}

Only rows your environment supports will appear. If exactly one network applies, the API may select it without returning this step.

Step 3 — Choose network and receive deposit instructions

Request — network must match a crypto_available_networks[].network value.

{  "method": "CRYPTO",  "token": "USDC",  "network": "USDC_POLYGON"}

Response (200) — show this to the payer

{  "success": true,  "message": "Payment method selected",  "data": {    "selected_payment_method": "CRYPTO",    "crypto_payment_info": {      "token": "USDC",      "amount": "100.12345678",      "network": "USDC_POLYGON",      "network_label": "Polygon",      "deposit_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",      "token_contract": "0x3c499c542cEF5F381Cfe7873482E8863E95bCC7d"    }  }}

The customer must send the exact amount on the correct chain and token; wrong chain or wrong amount delays or prevents auto-confirmation.

Step 4 — Payer confirms they have sent

POST /api/v1/checkout/:access_code/crypto-submitted

Response (200)

{  "success": true,  "message": "Awaiting payment confirmation"}

This moves the session toward awaiting on-chain confirmation while the provider matches the deposit. Rely on webhooks and/or GET /api/v1/client/payment/verify rather than assuming immediate completion.

Verify payment status

Same as other collection types:

GET /api/v1/client/payment/verify?reference=<your reference>

Signed with your business API key. Use this together with webhooks for a definitive server-side read.

Example success response (200)

Shape is shared across rails (card, mobile money, crypto). Values vary by transaction.

{  "transaction_id": "123e4567-e89b-12d3-a456-426614174000",  "transaction_reference": "TXN-REF-456789",  "status_name": "COMPLETED",  "status_id": 5,  "amount_tendered_with_fees": "100.00",  "amount_tendered_without_fees": "100.00",  "amount_received": "100.00",  "source_currency": "USD",  "target_currency": "USD",  "payment_completed": true,  "paymentCompleted": true,  "transaction_status": "COMPLETED",  "status": "COMPLETED",  "amount": "100.00",  "currency": "USD",  "message": "Payment status retrieved from local records"}

While status is still pending or processing, the server may consult the card provider when applicable; crypto flows still return the latest local status and message when no provider call is needed. Treat status_name / payment_completed as authoritative for your UI.

Deposit quotes (API-first)

When you do not want the hosted checkout UI, create and accept a DEPOSIT quote and present the returned payment details to the customer.

Stablecoin-related quote types

These are the usual client quote patterns when stablecoins are on the source or destination side (exact rules and fields are in Quotes and REST resource):

• Supported tokens: USDC, USDT (where enabled).
• DEPOSIT: customer sends stablecoin; credited per quote and wallet rules.
• WITHDRAWAL (stablecoin corridor): fiat from wallet to an external stablecoin address (beneficiary rules differ from fiat withdrawals—often self-beneficiary is created automatically).
• DIRECT_EXCHANGE: stablecoin in, fiat out to an external beneficiary—requires a beneficiary up front.

The platform applies conversion and fees once the quote is created; always use quote and acceptance responses rather than recomputing amounts client-side.

Example: create a crypto-funded deposit quote

Adapt fields to your corridor; this shape matches the historical API examples:

{  "source_currency": "USDC",  "target_currency": "NGN",  "source_amount": "1000.00",  "quote_type": "DEPOSIT",  "payment_network": "ETH",  "payment_address": "0x1234abcd5678ef901234abcd5678ef90abcd1234",  "tz": "UTC",  "origin_reference": "ORDER-2025-CRYPTO-001",  "on_behalf_of": "self"}

• payment_network and payment_address describe the funding leg for stablecoin-involved quotes.
• origin_reference and on_behalf_of follow the same business rules as other quote types—see Quotes and REST resource.

After accept, use payment_details / provider payloads from the response, then track completion via webhooks and transaction APIs.

Integration checklist

1. Discover currencies and limits with GET /api/v1/client/currencies (and related discovery calls from the Collections overview).
2. Initialize checkout with fiat amount / currency, or create a deposit quote for API-only flows.
3. Hosted path: run the select-method steps for CRYPTO until deposit instructions are returned; then crypto-submitted after the user sends.
4. Quote path: create → accept → show instructions from the accept response.
5. Reconcile with webhooks and payment/verify; handle retries idempotently.

Related docs

• Collections overview — shared discovery and patterns
• Card collection — initialize / verify field reference
• Mobile money collection — parallel hosted flow
• Quotes and REST resource — quote types, beneficiaries, crypto fields
• Webhooks — verifying and processing transaction events