Powered by Coinflow
Payments · Documentation
⌘K
Operational

One-Time Purchase Integration - Third-Party USDC Settlement

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

This guide walks you through integrating Coinflow checkout to accept one-time credit card purchases with USDC settlement to a third-party wallet address.

Prerequisites

Complete these steps before starting the integration.

Create your sandbox account

Register or login to your sandbox merchant account

Generate API keys

Create a sandbox API key for authentication

Add team members

Add team members to your sandbox account

Add chargeback protection

Add the protection script to every page of your app

Configure settlement

Configure settlement settings - Select Your Own Merchant Wallet

Quick Reference

Authorization Headers

Header Description
Authorization Your API key from the merchant dashboard
x-coinflow-auth-user-id Unique customer ID you use within your systems to identify the user
x-coinflow-auth-blockchain Use solana for Solana settlement
x-coinflow-auth-session-key JWT token authorizing the payer (valid for 24 hours)

Helpful Resources

Choose Your Implementation

API Only

Best for custom checkout UIs. Full control over the payment flow.

Step 1: Get a session key

Create a JWT token for the customer that authorizes them to call checkout endpoints.

curl --request GET \
     --url https://api-sandbox.coinflow.cash/api/auth/session-key \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'x-coinflow-auth-user-id: customer123'
{
  "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Session keys expire after 24 hours. Refresh them before expiration.

Step 2: Get pricing totals

Show the customer a quote inclusive of all fees.

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/checkout/totals/YOUR_MERCHANT_ID \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-coinflow-auth-session-key: SESSION_KEY' \
     --data '{
       "subtotal": { "cents": 100 },
       "settlementType": "USDC"
     }'
{
  "card": {
    "subtotal": { "cents": 100 },
    "creditCardFees": { "cents": 40 },
    "chargebackProtectionFees": { "cents": 0 },
    "gasFees": { "cents": 0 },
    "total": { "cents": 140 }
  },
  "ach": {
    "subtotal": { "cents": 100 },
    "creditCardFees": { "cents": 100 },
    "chargebackProtectionFees": { "cents": 0 },
    "gasFees": { "cents": 0 },
    "total": { "cents": 200 }
  }
}

Step 3: Tokenize the credit card

See PCI-compliant card tokenization for the “Tokenize New Card” implementation.

Step 4: Tokenize the destination wallet

Tokenize the wallet address that will receive the USDC settlement.

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/checkout/destination-auth-key \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "blockchain": "solana",
       "destination": "78C3dn4yUJST9pcX9GtA3yWBcKUCjDw1RWqw1MLpoUDh"
     }'
{
  "destinationAuthKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Step 5: Process a new card payment

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/checkout/card/YOUR_MERCHANT_ID \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-coinflow-auth-session-key: SESSION_KEY' \
     --data '{
       "subtotal": { "currency": "USD", "cents": 500 },
       "webhookInfo": {
         "example": "{\"wineId\": \"123abc\"}"
       },
       "card": {
         "cardToken": "411111YJM5TX1111",
         "expYear": "30",
         "expMonth": "10",
         "email": "test@gmail.com",
         "firstName": "John",
         "lastName": "Doe",
         "address1": "380 prospect ave",
         "city": "brooklyn",
         "zip": "11215",
         "state": "ny",
         "country": "US"
       },
       "destinationAuthKey": "DESTINATION_AUTH_KEY",
       "settlementType": "USDC"
     }'
{
  "paymentId": "f3fc8a34-680b-4b91-905b-1db5628bbb0e"
}

Step 6: Process saved card payments (returning users)

Re-tokenize the saved card with CVV first (see card tokenization docs - “Refresh Token w/ CVV” tab), then:

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/checkout/token/YOUR_MERCHANT_ID \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-coinflow-auth-session-key: SESSION_KEY' \
     --data '{
       "subtotal": { "currency": "USD", "cents": 500 },
       "webhookInfo": {
         "example": "{\"wineId\": \"123abc\"}"
       },
       "settlementType": "USDC",
       "token": "411111YJM5TX1111",
       "destinationAuthKey": "DESTINATION_AUTH_KEY"
     }'
{
  "paymentId": "0090c04b-1ae8-4672-a108-32874df36f11"
}

Step 7: Get payment details (optional)

curl --request GET \
     --url https://api-sandbox.coinflow.cash/api/merchant/payments/enhanced/PAYMENT_ID \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json'
{
  "info": {
    "firstName": "Dwayne",
    "lastName": "Johnson",
    "email": "customer@email.com",
    "streetAddress": "385 Prospect Ave",
    "city": "Brooklyn",
    "state": "NY",
    "zip": "11215",
    "country": "US",
    "bin": "411111",
    "expMonth": "10",
    "expYear": "30"
  }
}

Best for simple integrations. Generate a hosted checkout URL to redirect users or embed in an iframe.

Step 1: Tokenize the destination wallet

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/checkout/destination-auth-key \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "blockchain": "solana",
       "destination": "78C3dn4yUJST9pcX9GtA3yWBcKUCjDw1RWqw1MLpoUDh"
     }'
{
  "destinationAuthKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/checkout/link \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-coinflow-auth-user-id: user123' \
     --data '{
       "subtotal": { "currency": "USD", "cents": 500 },
       "email": "payer@gmail.com",
       "blockchain": "solana",
       "settlementType": "USDC",
       "destinationAuthKey": "DESTINATION_AUTH_KEY"
     }'
{
  "link": "https://sandbox.coinflow.cash/solana/purchase-v2/testtest?sessionKey=..."
}

Step 3: Listen for success events (optional)

When embedding the checkout in an iframe, you can listen for success events:

<iframe
  allow="payment"
  src="COINFLOW_CHECKOUT_URL"
  onLoad={() => {
    window.addEventListener('message', event => {
      if (typeof event.data === 'string') {
        const data = JSON.parse(event.data);
        if (data.data === 'success') {
          console.log('payment id', data.info.paymentId);
        }
      }
    });
  }}
/>

Step 4: Customize the UI

Customize the checkout UI on your dashboard.

React SDK

Best for React applications. Provides a pre-built checkout component.

Step 1: Install the SDK

npm install @coinflowlabs/react

Step 2: Get a session key

curl --request GET \
     --url https://api-sandbox.coinflow.cash/api/auth/session-key \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'x-coinflow-auth-user-id: user123'
{
  "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Session keys are valid for 30 minutes and must be refreshed afterwards.

Step 3: Tokenize the destination wallet

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/checkout/destination-auth-key \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "blockchain": "solana",
       "destination": "78C3dn4yUJST9pcX9GtA3yWBcKUCjDw1RWqw1MLpoUDh"
     }'
{
  "destinationAuthKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Step 4: Render the checkout component

import { CoinflowPurchase, SettlementType, Currency } from '@coinflowlabs/react';

function Checkout({ connection }) {
  return (
    <CoinflowPurchase
      sessionKey="SESSION_KEY"
      merchantId="your-merchant-id"
      env="sandbox"
      connection={connection}
      onSuccess={(...args) => {
        console.log('Purchase Success', args);
      }}
      blockchain="solana"
      settlementType={SettlementType.USDC}
      subtotal={{ cents: 300, currency: Currency.USD }}
      webhookInfo={{
        itemName: "sword",
        price: "10.99"
      }}
      email="user@email.com"
      chargebackProtectionData={[{
        productName: 'Sword',
        productType: "inGameProduct",
        quantity: 1,
        rawProductData: {
          productID: "sword12345",
          productDescription: "A legendary sword with magical powers.",
          productCategory: "Weapon"
        }
      }]}
      destinationAuthKey="DESTINATION_AUTH_KEY"
    />
  );
}

Step 5: Customize the UI

Customize the checkout UI on your dashboard.

3DS Integration

After implementing basic card checkout, add 3DS for enhanced security. Contact the Coinflow team to enable 3DS on your account.

Complete Checkout with 3DS Challenge

Learn how to add 3DS to your new card and saved card requests

Chargeback Protection

Add the protection script

Add the chargeback protection script to every page of your app. This script analyzes user behavior to detect potential fraud.

On sandbox, use the test partnerId provided by the Coinflow team when configuring the protection script.

Add protection data to checkout requests

Pass chargebackProtectionData along with these headers:

  • x-device-id - Device ID from the protection script
  • x-coinflow-client-ip - Payer’s IP address
  • user-agent - Payer’s User Agent
curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/checkout/card/YOUR_MERCHANT_ID \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.3 Safari/605.1.15' \
     --header 'x-coinflow-auth-session-key: SESSION_KEY' \
     --header 'x-coinflow-client-ip: 123.123.123.123' \
     --header 'x-device-id: 123456789' \
     --data '{
       "subtotal": { "currency": "USD", "cents": 500 },
       "webhookInfo": {
         "example": "{\"wineId\": \"123abc\"}"
       },
       "card": {
         "cardToken": "411111YJM5TX1111",
         "expYear": "30",
         "expMonth": "10",
         "firstName": "John",
         "lastName": "Doe",
         "email": "test@gmail.com",
         "address1": "380 Prospect Ave",
         "city": "Brooklyn",
         "zip": "11215",
         "state": "NY",
         "country": "US"
       },
       "destinationAuthKey": "DESTINATION_AUTH_KEY",
       "chargebackProtectionData": [{
         "productType": "alcohol",
         "rawProductData": {
           "description": "pass as much description about the purchase here",
           "region": "CA",
           "yearsOld": 20
         },
         "productName": "California Cab",
         "quantity": 1
       }],
       "settlementType": "USDC"
     }'

Complete the chargeback protection form to get your chargebackProtectionData.productType and partnerId for production.

Next Steps

Test Your Integration

Use sandbox test cards to verify your implementation

Configure Webhooks

Receive real-time payment notifications

Go Live

Create your production merchant account

API Reference

Explore the complete API documentation