One-Time Purchase Integration - Solana Contract Settlement

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

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

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 Solana program

Whitelist your program to receive USDC settlement

Quick Reference

Authorization Headers

Header	Description
`Authorization`	Your API key from the merchant dashboard
`x-coinflow-auth-wallet`	User’s Solana wallet address
`x-coinflow-auth-blockchain`	Use `solana` for Solana contract settlement
`x-coinflow-auth-session-key`	JWT token authorizing the payer

Helpful Resources

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 --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-blockchain: solana' \
>      --header 'x-coinflow-auth-wallet: USER_WALLET_ADDRESS' \
>      --data '{
>        "webhookInfo": {
>          "depositId": "123-abc-456"
>        },
>        "subtotal": {
>          "currency": "USD",
>          "cents": 500
>        },
>        "settlementType": "Credits",
>        "email": "customer@example.com",
>        "blockchain": "solana",
>        "chargebackProtectionData": [{
>          "productType": "inGameProduct",
>          "productName": "In-Game Credits",
>          "quantity": 1,
>          "rawProductData": {
>            "description": "Purchase credits for gameplay"
>          }
>        }],
>        "deviceId": "123456789",
>        "supportEmail": "support@yourcompany.com"
>      }'

Step 2: Create a redeem transaction

After the payer completes checkout, create a redeem transaction to settle USDC to your contract. Create a base58 encoded transaction for your whitelisted program.

$ curl --request POST \
>      --url https://api-sandbox.coinflow.cash/api/redeem \
>      --header 'accept: application/json' \
>      --header 'content-type: application/json' \
>      --header 'x-coinflow-auth-blockchain: solana' \
>      --header 'x-coinflow-auth-wallet: USER_WALLET_ADDRESS' \
>      --data '{
>        "subtotal": {
>          "currency": "USD",
>          "cents": 500
>        },
>        "merchantId": "YOUR_MERCHANT_ID",
>        "transaction": "BASE58_ENCODED_TRANSACTION",
>        "chargebackProtectionData": [{
>          "productType": "inGameProduct",
>          "productName": "In-Game Credits",
>          "quantity": 1
>        }]
>      }'

Step 3: Sign and send the transaction

Have the user’s wallet sign and send the transaction.

1 const { Connection, Keypair, VersionedTransaction } = require('@solana/web3.js');
2 const bs58 = require('bs58');
3 
4 async function signTransaction(base58Transaction, keypair) {
5   const decodedTransactionBytes = bs58.decode(base58Transaction);
6   const versionedTransaction = VersionedTransaction.deserialize(decodedTransactionBytes);
7   versionedTransaction.sign([keypair]);
8   const serializedTransaction = versionedTransaction.serialize();
9   return bs58.encode(serializedTransaction);
10 }

Chargeback Protection

Add the protection script

Add the chargeback protection script to every page of your app.

Send user events

Track key user actions throughout their journey.

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

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

$	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-blockchain: solana' \
>	--header 'x-coinflow-auth-wallet: USER_WALLET_ADDRESS' \
>	--data '{
>	"webhookInfo": {
>	"depositId": "123-abc-456"
>	},
>	"subtotal": {
>	"currency": "USD",
>	"cents": 500
>	},
>	"settlementType": "Credits",
>	"email": "customer@example.com",
>	"blockchain": "solana",
>	"chargebackProtectionData": [{
>	"productType": "inGameProduct",
>	"productName": "In-Game Credits",
>	"quantity": 1,
>	"rawProductData": {
>	"description": "Purchase credits for gameplay"
>	}
>	}],
>	"deviceId": "123456789",
>	"supportEmail": "support@yourcompany.com"
>	}'

1	const { Connection, Keypair, VersionedTransaction } = require('@solana/web3.js');
2	const bs58 = require('bs58');
3
4	async function signTransaction(base58Transaction, keypair) {
5	const decodedTransactionBytes = bs58.decode(base58Transaction);
6	const versionedTransaction = VersionedTransaction.deserialize(decodedTransactionBytes);
7	versionedTransaction.sign([keypair]);
8	const serializedTransaction = versionedTransaction.serialize();
9	return bs58.encode(serializedTransaction);
10	}