> 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 - Stellar BYO Wallet 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 on the Stellar network — without requiring a smart contract. USDC is sent directly to your configured settlement wallet.

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

Set up your [BYO Wallet](/guides/checkout/settlement-locations/merchant-byo-wallet-settlement) — your own Stellar wallet with a USDC trustline to receive USDC revenue.

> **Info**
>
> USDC transfers to a BYO wallet do **not** require a `stellarTransaction`. No smart contract whitelisting or transaction construction is needed.

> **Warning**
>
> Stellar checkout does not support Credits settlement or partial purchases where the customer contributes their own USDC alongside a credit card payment.

## 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 from your system                                                                             |
| `x-coinflow-auth-blockchain`  | Use `stellar` for Stellar settlement                                                                            |
| `x-coinflow-auth-session-key` | [JWT token](/api-reference/api-reference/authentication/get-session-key) authorizing the payer (valid 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

#### Checkout Link

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

### Step 1: Generate the checkout link

**`Request`**

```bash title="Request"
curl -X POST https://api-sandbox.coinflow.cash/api/checkout/link \
  -H "x-coinflow-auth-user-id: customer123" \
  -H "x-coinflow-auth-blockchain: stellar" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "subtotal": {
      "cents": 500,
      "currency": "USD"
    },
    "blockchain": "stellar",
    "settlementType": "USDC",
    "chargebackProtectionData": [{
      "productType": "inGameProduct",
      "productName": "Digital Item",
      "quantity": 1,
      "rawProductData": {
        "description": "A digital purchase"
      }
    }],
    "deviceId": "123456789"
  }'
```

**`Response`**

```json title="Response"
{
  "link": "https://sandbox.coinflow.cash/stellar/purchase-v2/YOUR_MERCHANT_ID?sessionKey=eyJhbGci..."
}
```

### Step 2: Use the checkout link

**Embed in an iframe**

```html
<iframe
  allow="payment"
  src="CHECKOUT_LINK_FROM_STEP_1"
  style="width: 100%; height: 600px; border: none;"
/>
```

### Step 3: Handle success events

Listen for payment completion when using an iframe:

```javascript
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);
    }
  }
});
```

#### React SDK

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

### Step 1: Install the SDK

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

### Step 2: Tokenize checkout parameters

Encrypt checkout parameters from your backend to prevent tampering.

**`Request`**

```bash title="Request"
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 '{
       "subtotal": {
         "currency": "USD",
         "cents": 500
       },
       "email": "customer@example.com",
       "blockchain": "stellar",
       "settlementType": "USDC",
       "chargebackProtectionData": [{
         "productType": "inGameProduct",
         "productName": "Digital Item",
         "quantity": 1,
         "rawProductData": {
           "description": "A digital purchase"
         }
       }],
       "deviceId": "123456789"
     }'
```

**`Response`**

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

### Step 3: Render the checkout component

```tsx
import { CoinflowPurchase } from '@coinflowlabs/react';

function Checkout() {
  const stellarWallet = {
    address: "GBCG42WTVWPO4Q6OZCYI3D6ZSTFMO6S2WPUFM3MYO7LEDFCZU3IDALU",
    sendTransaction: async (base64Xdr: string) => "tx_hash",
    signTransaction: async (base64Xdr: string) => "signed_xdr",
    signMessage: async (message: string) => "signature",
  };

  return (
    <CoinflowPurchase
      wallet={stellarWallet}
      merchantId="your-merchant-id"
      env="sandbox"
      blockchain="stellar"
      jwtToken="JWT_TOKEN_FROM_STEP_2"
      subtotal={{ cents: 500, currency: 'USD' }}
      onSuccess={(paymentId) => {
        console.log('Payment successful:', paymentId);
      }}
    />
  );
}
```

> **Info**
>
> For direct USDC transfers, do **not** pass a `transaction` prop. Omitting it tells Coinflow to settle directly to your configured wallet.

### Step 4: Configure your dashboard

1. [Customize the UI](/guides/developer-resources/custom-branding) to match your brand from [your dashboard](https://sandbox-merchant.coinflow.cash/theme)
2. [Whitelist your domain](https://sandbox-merchant.coinflow.cash/frame-ancestors) to prevent unauthorized embedding

#### API Only

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

### Step 1: 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: customer123'
```

**`Response`**

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

### Step 2: Get pricing totals

**`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_FROM_STEP_1' \
     --data '{
       "subtotal": { "cents": 500 },
       "settlementType": "USDC"
     }'
```

**`Response`**

```json title="Response"
{
  "card": {
    "subtotal": { "cents": 500 },
    "creditCardFees": { "cents": 40 },
    "chargebackProtectionFees": { "cents": 0 },
    "gasFees": { "cents": 0 },
    "total": { "cents": 540 }
  }
}
```

### Step 3: Tokenize the credit card

See [PCI-compliant card tokenization](/recipes/recipes/pci-compliant-card-tokenization) for implementation details.

### Step 4: Tokenize checkout parameters

**`Request`**

```bash title="Request"
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 '{
       "subtotal": { "currency": "USD", "cents": 500 },
       "email": "customer@example.com",
       "blockchain": "stellar",
       "settlementType": "USDC",
       "chargebackProtectionData": [{
         "productName": "Digital Item",
         "quantity": 1,
         "productType": "inGameProduct",
         "rawProductData": {
           "description": "A digital purchase"
         }
       }],
       "deviceId": "123456789"
     }'
```

**`Response`**

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

### Step 5: Process the 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' \
     --header 'x-coinflow-client-ip: CUSTOMER_IP_ADDRESS' \
     --header 'x-device-id: DEVICE_ID_FROM_PROTECTION_SCRIPT' \
     --header 'user-agent: CUSTOMER_USER_AGENT' \
     --data '{
       "subtotal": { "currency": "USD", "cents": 500 },
       "jwtToken": "JWT_TOKEN_FROM_STEP_4",
       "card": {
         "cardToken": "TOKENIZED_CARD_FROM_STEP_3",
         "expYear": "30",
         "expMonth": "10",
         "email": "customer@example.com",
         "firstName": "John",
         "lastName": "Doe",
         "address1": "123 Main St",
         "city": "New York",
         "zip": "10001",
         "state": "NY",
         "country": "US"
       }
     }'
```

**`Response`**

```json title="Response"
{
  "paymentId": "f3fc8a34-680b-4b91-905b-1db5628bbb0e"
}
```

**For saved cards:**

Re-tokenize the saved card with CVV first (see [card tokenization docs](/recipes/recipes/pci-compliant-card-tokenization)), 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' \
     --header 'x-coinflow-client-ip: CUSTOMER_IP_ADDRESS' \
     --header 'x-device-id: DEVICE_ID' \
     --data '{
       "subtotal": { "currency": "USD", "cents": 500 },
       "jwtToken": "JWT_TOKEN_FROM_STEP_4",
       "token": "REFRESHED_CARD_TOKEN"
     }'
```

**`Response`**

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

### Step 6: Verify the payment (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'
```

---

## 3DS Authentication

After implementing basic checkout, add 3DS for stronger authentication. Contact Coinflow 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

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.

**`Sign Up`**

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

**`Sign In`**

```bash title="Sign In"
curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/events \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "eventType": "SignIn",
       "customerId": "user-123-abc",
       "country": "US",
       "email": "john@example.com"
     }'
```

### 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](/guides/checkout/payment-security-risk-management/fraud-protection/implement-chargeback-protection) |
| `x-coinflow-client-ip` | Customer's IPv4 address                                                                                                                               |
| `user-agent`           | Customer's browser user agent                                                                                                                         |

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

---

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