One-Time Purchase Integration - Stellar Contract Settlement

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

Quick Reference

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();

Choose Your Implementation

$
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
});

3DS Authentication

After implementing basic checkout, add 3DS for stronger authentication. Contact Coinflow to enable 3DS on your account.

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:

Next Steps