One-Time Purchase Integration - USDC Settlement

This guide walks you through integrating Coinflow’s checkout to accept one-time credit card purchases with USDC settlement. Choose from three implementation methods based on your needs.

Prerequisites

Complete these steps before starting the integration.

Create your sandbox account

Generate API keys

Create a sandbox API key for authentication

Configure settlement

Choose where to receive your USDC revenue:

Coinflow Wallet - Managed wallet within Coinflow
BYO Wallet - Your own external wallet

Quick Reference

Authorization Headers

Header	Description
`Authorization`	Your API key from the merchant dashboard
`x-coinflow-auth-user-id`	Unique customer ID from your system
`x-coinflow-auth-blockchain`	Use `solana` when settling to a Coinflow wallet. For BYO wallets, set this to the blockchain where USDC will be sent for settlement.
`x-coinflow-auth-session-key`	JWT token authorizing the payer (valid 24 hours)

Helpful Resources

Choose Your Implementation

React SDK

Checkout Link

API Only

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

Step 1: Install the SDK

$ npm install @coinflowlabs/react

Step 2: Generate a session key

Create a JWT token to authorize the payer. Call this from your backend.

$ 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'

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

Step 3: Tokenize checkout parameters

Encrypt checkout parameters to prevent tampering. Call this from your backend.

$ curl --request POST \
>      --url https://api-sandbox.coinflow.cash/api/checkout/jwt-token \
>      --header 'Authorization: YOUR_API_KEY' \
>      --header 'accept: application/json' \
>      --header 'content-type: application/json' \
>      --data '{
>        "webhookInfo": {
>          "itemName": "sword",
>          "price": "10.99"
>        },
>        "subtotal": {
>          "currency": "USD",
>          "cents": 500
>        },
>        "email": "customer@example.com",
>        "blockchain": "solana",
>        "settlementType": "USDC",
>        "chargebackProtectionData": [{
>          "productType": "inGameProduct",
>          "productName": "Sword",
>          "quantity": 1,
>          "rawProductData": {
>            "productID": "sword12345",
>            "productDescription": "A legendary sword"
>          }
>        }]
>      }'

Step 4: Render the checkout component

1 import { CoinflowPurchase, SettlementType, Currency } from '@coinflowlabs/react';
2 
3 function Checkout() {
4   return (
5     <CoinflowPurchase
6       merchantId="your-merchant-id"
7       env="sandbox"
8       sessionKey="SESSION_KEY_FROM_STEP_2"
9       jwtToken="JWT_TOKEN_FROM_STEP_3"
10       settlementType={SettlementType.USDC}
11       subtotal={{ cents: 500, currency: Currency.USD }}
12       email="customer@example.com"
13       webhookInfo={{
14         itemName: "sword",
15         price: "10.99"
16       }}
17       chargebackProtectionData={[{
18         productName: 'Sword',
19         productType: 'inGameProduct',
20         quantity: 1,
21         rawProductData: {
22           productID: "sword12345",
23           productDescription: "A legendary sword"
24         }
25       }]}
26       onSuccess={(paymentId) => {
27         console.log('Payment successful:', paymentId);
28         // Redirect user to success page
29       }}
30     />
31   );
32 }

Step 5: Configure your dashboard

Customize the UI to match your brand from your dashboard
Whitelist your domain to prevent unauthorized embedding

Chargeback Protection

Improve approval rates and reduce fraud by sharing payer events with Coinflow.

Send user events

Track key user actions throughout their journey on your app.

$ curl --request POST \
>      --url https://api-sandbox.coinflow.cash/api/events \
>      --header 'Authorization: YOUR_API_KEY' \
>      --header 'content-type: application/json' \
>      --data '{
>        "eventType": "SignUp",
>        "customerId": "user-123-abc",
>        "country": "US",
>        "username": "johndoe",
>        "email": "john@example.com",
>        "firstName": "John",
>        "lastName": "Doe"
>      }'

Required headers for checkout

When processing payments, include these headers for chargeback protection:

Header	Description
`x-device-id`	Device ID from the chargeback protection script
`x-coinflow-client-ip`	Customer’s IP address
`user-agent`	Customer’s browser user agent

On sandbox, use partnerId = COINFTEST when configuring the protection script.

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