CheckoutImplementation OverviewImplementation Guides

One-Time Purchase Integration - Third-Party USDC Settlement

Accept credit card payments and settle USDC directly to a third-party wallet

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.

1

Create your sandbox account

Register or login to your sandbox merchant account

2

Generate API keys

Create a sandbox API key for authentication

3

Add team members

Add team members to your sandbox account

4

Add chargeback protection

Add the protection script to every page of your app

Quick Reference

HeaderDescription
AuthorizationYour API key from the merchant dashboard
x-coinflow-auth-user-idUnique customer ID you use within your systems to identify the user
x-coinflow-auth-blockchainUse solana for Solana settlement
x-coinflow-auth-session-keyJWT token authorizing the payer (valid for 24 hours)

Choose Your Implementation

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'

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"
>     }'

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"
>     }'

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"
>     }'

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"
>     }'

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'

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 partnerId = COINFTEST 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
Request with Chargeback Protection
$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