> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.coinflow.cash/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coinflow.cash/_mcp/server.

# One-Time Purchase Integration - Third-Party USDC Settlement

> **Warning**
>
> **This page is for advanced / cryptocurrency-native companies.** If that's not you, head back to the [Quickstart](/guides/getting-started/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

> **Warning**
>
> Complete these steps before starting the integration.

#### Create your sandbox account

[Register](https://sandbox-merchant.coinflow.cash/register) or [login](https://sandbox-merchant.coinflow.cash/login) to your sandbox merchant account

#### Generate API keys

[Create a sandbox API key](https://sandbox-merchant.coinflow.cash/api-keys) for authentication

#### Add team members

[Add team members](https://sandbox-merchant.coinflow.cash/users-and-roles) to your sandbox account

#### Add chargeback protection

[Add the protection script](/guides/checkout/payment-security-risk-management/fraud-protection/implement-chargeback-protection#how-to-add-chargeback-protection) to every page of your app

#### Configure settlement

[Configure settlement settings](https://sandbox-merchant.coinflow.cash/settings) - Select [Your Own Merchant Wallet](/guides/checkout/settlement-locations/merchant-byo-wallet-settlement)

## Quick Reference

#### Authorization Headers

| Header                        | Description                                                                                                         |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `Authorization`               | Your API key from [the merchant dashboard](https://sandbox-merchant.coinflow.cash/api-keys)                         |
| `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](/api-reference/api-reference/authentication/get-session-key) authorizing the payer (valid for 24 hours) |

#### Helpful Resources

* [Test card numbers for sandbox](/guides/checkout/testing/testing-credit-cards)
* [Checkout webhooks](/guides/developer-resources/webhooks/checkout-webhooks)
* [Custom branding](/guides/developer-resources/custom-branding)

---

## 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.

**`Request`**

```bash title="Request"
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'
```

**`Response`**

```json title="Response"
{
  "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

> **Warning**
>
> Session keys expire after 24 hours. Refresh them before expiration.

### Step 2: Get pricing totals

Show the customer a quote inclusive of all fees.

**`Request`**

```bash title="Request"
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"
     }'
```

**`Response`**

```json title="Response"
{
  "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](/recipes/recipes/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.

**`Request`**

```bash title="Request"
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"
     }'
```

**`Response`**

```json title="Response"
{
  "destinationAuthKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Step 5: Process a new card payment

**`Request`**

```bash title="Request"
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"
     }'
```

**`Response`**

```json title="Response"
{
  "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](/recipes/recipes/pci-compliant-card-tokenization) - "Refresh Token w/ CVV" tab), then:

**`Request`**

```bash title="Request"
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"
     }'
```

**`Response`**

```json title="Response"
{
  "paymentId": "0090c04b-1ae8-4672-a108-32874df36f11"
}
```

### Step 7: Get payment details (optional)

**`Request`**

```bash title="Request"
curl --request GET \
     --url https://api-sandbox.coinflow.cash/api/merchant/payments/enhanced/PAYMENT_ID \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json'
```

**`Response`**

```json title="Response"
{
  "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"
  }
}
```

#### Checkout Link

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

### Step 1: Tokenize the destination wallet

**`Request`**

```bash title="Request"
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"
     }'
```

**`Response`**

```json title="Response"
{
  "destinationAuthKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Step 2: Generate the checkout link

**`Request`**

```bash title="Request"
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"
     }'
```

**`Response`**

```json title="Response"
{
  "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:

```javascript
<iframe
  allow="payment"
  src="COINFLOW_CHECKOUT_URL"
  onLoad={() => {
    window.addEventListener('message', event => {
      // Use 'https://coinflow.cash' in production.
      if (event.origin !== 'https://sandbox.coinflow.cash') return;
      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](/guides/developer-resources/custom-branding) on [your dashboard](https://sandbox-merchant.coinflow.cash/theme).

#### React SDK

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

### Step 1: Install the SDK

```bash
npm install @coinflowlabs/react
```

### Step 2: Get a session key

**`Request`**

```bash title="Request"
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'
```

**`Response`**

```json title="Response"
{
  "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

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

### Step 3: Tokenize the destination wallet

**`Request`**

```bash title="Request"
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"
     }'
```

**`Response`**

```json title="Response"
{
  "destinationAuthKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Step 4: Render the checkout component

```tsx
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](/guides/developer-resources/custom-branding) on [your dashboard](https://sandbox-merchant.coinflow.cash/theme).

---

## 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](/recipes/recipes/complete-checkout-with-3-ds-challenge-react)

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

---

## Chargeback Protection

### Add the protection script

Add the [chargeback protection script](/guides/checkout/payment-security-risk-management/fraud-protection/implement-chargeback-protection#how-to-add-chargeback-protection) to every page of your app. This script analyzes user behavior to detect potential fraud.

> **Info**
>
> 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

**`Request with Chargeback Protection`**

```bash title="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](https://forms.gle/9wpW2UVnkjpKXVdWA) to get your `chargebackProtectionData.productType` and `partnerId` for production.

---

## Next Steps

#### [Test Your Integration](/guides/checkout/testing/testing-credit-cards)

Use sandbox test cards to verify your implementation

#### [Configure Webhooks](/guides/developer-resources/webhooks/checkout-webhooks)

Receive real-time payment notifications

#### [Go Live](https://merchant.coinflow.cash/register)

Create your production merchant account

#### [API Reference](/api-reference/api-reference/checkout/card-checkout)

Explore the complete API documentation