CheckoutImplementation OverviewImplementation Guides

One-Time Purchase Integration - Direct USDC Transfer (Stellar)

Accept credit card payments and settle USDC to your BYO wallet on Stellar

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

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 chargeback protection

Add the protection script to every page of your app

4

Configure settlement

Set up your BYO Wallet — your own Stellar wallet with a USDC trustline to receive USDC revenue.

Direct USDC transfers do not require a stellarTransaction. No smart contract whitelisting or transaction construction is needed.

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

Quick Reference

HeaderDescription
AuthorizationYour API key from the merchant dashboard
x-coinflow-auth-user-idUnique customer ID from your system
x-coinflow-auth-blockchainUse stellar for Stellar settlement
x-coinflow-auth-session-keyJWT token authorizing the payer (valid 24 hours)

Choose Your Implementation

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

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

Embed in an iframe

1<iframe
2  allow="payment"
3  src="CHECKOUT_LINK_FROM_STEP_1"
4  style="width: 100%; height: 600px; border: none;"
5/>

Step 3: Handle success events

Listen for payment completion when using an iframe:

1window.addEventListener('message', (event) => {
2  if (typeof event.data === 'string') {
3    const data = JSON.parse(event.data);
4    if (data.data === 'success') {
5      console.log('Payment ID:', data.info.paymentId);
6    }
7  }
8});

3DS Authentication

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

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:

HeaderDescription
x-device-idDevice ID from the chargeback protection script
x-coinflow-client-ipCustomer’s IPv4 address
user-agentCustomer’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