One-Time Purchase Integration - Stellar Contract Settlement

Accept credit card payments and settle USDC directly to your Stellar smart contract

This page is for advanced / cryptocurrency-native companies. If that’s not you, head back to the Quickstart for the standard flows.

This guide walks you through integrating Coinflow checkout to accept one-time credit card purchases with USDC settlement to your whitelisted Stellar Soroban contract.

Prerequisites

Complete these steps before starting the integration.

Create your sandbox account

Generate API keys

Create a sandbox API key for authentication

Add chargeback protection

Add the protection script to every page of your app

Whitelist your Stellar contract

Whitelist your contract address for settlement

Quick Reference

Authorization Headers

Header	Description
`Authorization`	Your API key from the merchant dashboard
`x-coinflow-auth-wallet`	User’s Stellar wallet address (G-prefixed)
`x-coinflow-auth-blockchain`	Use `stellar` for Stellar contract settlement
`x-coinflow-auth-session-key`	JWT token authorizing the payer

Helpful Resources

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

Build Your Stellar Transaction

Before integrating checkout, you need to build a stellarTransaction — a base64-encoded XDR string representing your Soroban contract invocation.

Generate TypeScript Bindings

Use the Stellar CLI to generate TypeScript bindings for your contract:

$ # Use --network mainnet for production
$ stellar contract bindings typescript \
>   --network testnet \
>   --contract-id YOUR_CONTRACT_ID \
>   --output-dir ./your-contract-client

Build and Encode the Transaction

1 import {YourContractClient} from './your-contract-client';
2 
3 // Initialize your contract client
4 const client = new YourContractClient({
5   contractId: 'YOUR_CONTRACT_ID',
6   networkPassphrase: 'Test SDF Network ; September 2015', // Mainnet: 'Public Global Stellar Network ; September 2015'
7   rpcUrl: 'https://soroban-testnet.stellar.org',          // Mainnet: use your Soroban RPC provider
8   publicKey: sourceAccountPublicKey,
9 });
10 
11 // Build the contract invocation
12 const tx = await client.your_purchase_function({
13   usdc: 'CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA',
14   payer: 'CA6F7DX4RBZLENHGLPPTGQA4CRNNH3U6QJ3KD7HQLN46YENHTWJRZUOH',
15   recipient: customerWalletAddress,
16 });
17 
18 // Convert to base64 XDR string
19 const stellarTransaction = tx.toXDR();

The payer should be the Coinflow checkout contract address:

Environment	Checkout Contract Address
Sandbox	`CA6F7DX4RBZLENHGLPPTGQA4CRNNH3U6QJ3KD7HQLN46YENHTWJRZUOH`
Production	`CDUVNW53LTEPPA6SWEGMAV2KJT4YCRECSLRB7XG3KEN3B62YK6HBKG7S`

Choose Your Implementation

Checkout Link

React SDK

API Only

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

Step 1: Generate the checkout link

$ curl -X POST https://api-sandbox.coinflow.cash/api/checkout/link \
>   -H "Authorization: YOUR_API_KEY" \
>   -H "x-coinflow-auth-wallet: GBCG42WTVWPO4Q6OZCYI3D6ZSTFMO6S2WPUFM3MYO7LEDFCZU3IDALU" \
>   -H "x-coinflow-auth-blockchain: stellar" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "email": "customer@example.com",
>     "subtotal": {
>       "cents": 500,
>       "currency": "USD"
>     },
>     "blockchain": "stellar",
>     "stellarTransaction": "AAAAAgAAAABh...(base64 XDR)...",
>     "chargebackProtectionData": [{
>       "productType": "inGameProduct",
>       "productName": "NFT Item",
>       "quantity": 1,
>       "rawProductData": {
>         "description": "A digital collectible on Stellar"
>       }
>     }],
>     "deviceId": "123456789"
>   }'

Step 2: Use the checkout link

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:

1 window.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       // Handle successful payment
7     }
8   }
9 });

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:

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

On sandbox, use the test partnerId provided by the Coinflow team 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

$	# Use --network mainnet for production
$	stellar contract bindings typescript \
>	--network testnet \
>	--contract-id YOUR_CONTRACT_ID \
>	--output-dir ./your-contract-client

1	import {YourContractClient} from './your-contract-client';
2
3	// Initialize your contract client
4	const client = new YourContractClient({
5	contractId: 'YOUR_CONTRACT_ID',
6	networkPassphrase: 'Test SDF Network ; September 2015', // Mainnet: 'Public Global Stellar Network ; September 2015'
7	rpcUrl: 'https://soroban-testnet.stellar.org', // Mainnet: use your Soroban RPC provider
8	publicKey: sourceAccountPublicKey,
9	});
10
11	// Build the contract invocation
12	const tx = await client.your_purchase_function({
13	usdc: 'CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA',
14	payer: 'CA6F7DX4RBZLENHGLPPTGQA4CRNNH3U6QJ3KD7HQLN46YENHTWJRZUOH',
15	recipient: customerWalletAddress,
16	});
17
18	// Convert to base64 XDR string
19	const stellarTransaction = tx.toXDR();

$	curl -X POST https://api-sandbox.coinflow.cash/api/checkout/link \
>	-H "Authorization: YOUR_API_KEY" \
>	-H "x-coinflow-auth-wallet: GBCG42WTVWPO4Q6OZCYI3D6ZSTFMO6S2WPUFM3MYO7LEDFCZU3IDALU" \
>	-H "x-coinflow-auth-blockchain: stellar" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"email": "customer@example.com",
>	"subtotal": {
>	"cents": 500,
>	"currency": "USD"
>	},
>	"blockchain": "stellar",
>	"stellarTransaction": "AAAAAgAAAABh...(base64 XDR)...",
>	"chargebackProtectionData": [{
>	"productType": "inGameProduct",
>	"productName": "NFT Item",
>	"quantity": 1,
>	"rawProductData": {
>	"description": "A digital collectible on Stellar"
>	}
>	}],
>	"deviceId": "123456789"
>	}'

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

1	window.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	// Handle successful payment
7	}
8	}
9	});

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