PayoutsCard Payments Implementation

Basic Card Checkout Guide

Basic Card Checkout Guide

Integrating Coinflow checkout is straightforward:

1. Choose Your Checkout Method

Pick the integration style that fits your needs:

  • Checkout Link - Redirect customers to a hosted payment page (5 min setup)
  • React SDK - Drop in pre-built React components (15 min setup)
  • API Integration - Full control with your custom UI (30 min setup)

2. Set Up Webhooks

Configure webhooks to receive payment notifications and complete your business logic:

  • Credit customer accounts with sweeps coins/cash
  • Unlock purchased content or features
  • Update your database with transaction details
  • Send confirmation emails

3. Add Fraud Protection Features (Optional)

Enhance your checkout with optional features:

Getting Started

Complete these prerequisites before integrating any checkout method.

⚠️ Account Setup Required

Complete these steps before integrating:

  1. Register a sandbox merchant account or login
  2. Create a sandbox API key
  3. Add team members to your sandbox account
  4. Configure settlement settings - choose between:
  5. Add chargeback protection script to every page

Developer Resources

Quick Reference

API Authentication

All API requests require these headers:

HeaderDescription
AuthorizationYour API key from the merchant dashboard
x-coinflow-auth-user-idUnique customer ID from your system
x-coinflow-auth-blockchainSet to solana if using Coinflow in-app wallet
x-coinflow-auth-session-keyJWT token (valid 24 hours) authorizing the payer

Integration Methods

Choose the method that best fits your technical requirements and timeline.

⏱️ Setup time: ~5 minutes | Best for: Quick integration, minimal code

The fastest way to start accepting payments. Generate a secure checkout URL and redirect customers to a hosted payment page.

When to Use

  • You want to integrate payments quickly
  • You prefer a hosted solution
  • You don’t need deep UI customization

Implementation Steps

Step 1: Share Payer Events

Share key customer lifecycle events to improve approval rates.

$# Sign Up Event
>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": "therock72",
>    "email": "dwaynejohnson@gmail.com",
>    "firstName": "Dwayne",
>    "lastName": "Johnson"
>  }'
$# Sign In Event
>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": "dwaynejohnson@gmail.com"
>  }'

See all event types →

Create a hosted checkout page for your customers.

$curl --request POST \
>  --url https://api-sandbox.coinflow.cash/api/checkout/link \
>  --header 'Authorization: YOUR_API_KEY' \
>  --header 'content-type: application/json' \
>  --header 'x-coinflow-auth-user-id: user123' \
>  --data '{
>    "subtotal": {
>      "currency": "USD",
>      "cents": 500
>    },
>    "email": "payer@gmail.com",
>    "blockchain": "solana",
>    "settlementType": "USDC"
>  }'

Response:

1{
2  "link": "https://sandbox.coinflow.cash/solana/purchase-v2/..."
3}

Step 3: Redirect or Embed

Option A: Redirect - Send users to the checkout link

Option B: Embed in iframe - Display checkout inline

1<iframe
2  allow="payment"
3  src="COINFLOW_CHECKOUT_URL"
4  onLoad={() => {
5    window.addEventListener('message', event => {
6      if (typeof event.data === 'string') {
7        const data = JSON.parse(event.data);
8        if (data.data === 'success') {
9          console.log('Payment ID:', data.info.paymentId);
10          // Handle success - credit user account, etc.
11        }
12      }
13    });
14  }}
15/>

Step 4: Customize & Secure

  1. Customize branding to match your brand
  2. Whitelist your domain to prevent unauthorized use

React SDK Implementation

⏱️ Setup time: ~15 minutes | Best for: React applications

Pre-built React components that handle the complete checkout flow.

When to Use

  • You’re building with React
  • You want pre-built UI components
  • You need more customization than the checkout link

Implementation Steps

Step 1: Install Package

$npm install @coinflowlabs/react

Step 2: Share Payer Events

Same as Checkout Link Step 1

Step 3: Generate Session Key

$curl --request GET \
>  --url https://api-sandbox.coinflow.cash/api/auth/session-key \
>  --header 'Authorization: YOUR_API_KEY' \
>  --header 'x-coinflow-auth-user-id: user123'

Response:

1{
2  "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
3}

⚠️ Important: Session keys expire after 30 minutes and must be refreshed.

Step 4: Tokenize Checkout Parameters

Encrypt checkout parameters to prevent tampering.

$curl --request POST \
>  --url https://api-sandbox.coinflow.cash/api/checkout/jwt-token \
>  --header 'Authorization: YOUR_API_KEY' \
>  --header 'content-type: application/json' \
>  --data '{
>    "webhookInfo": {
>      "example": "{\"productId\":\"123abc\"}"
>    },
>    "subtotal": {
>      "currency": "USD",
>      "cents": 500
>    },
>    "email": "iamabuyer@gmail.com",
>    "blockchain": "solana",
>    "settlementType": "USDC",
>    "chargebackProtectionData": [{
>      "productName": "shield",
>      "quantity": 1,
>      "productType": "inGameProduct",
>      "rawProductData": {
>        "description": "A shield for in-game use"
>      }
>    }],
>    "supportEmail": "support@mycompany.com"
>  }'

Step 5: Implement Component

1import { CoinflowPurchase, SettlementType, Currency } from '@coinflowlabs/react';
2
3function CheckoutPage() {
4  return (
5    <CoinflowPurchase
6      sessionKey="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
7      merchantId="YOUR_MERCHANT_ID"
8      env="sandbox"
9      onSuccess={(args) => {
10        console.log('Purchase Success:', args);
11        // Credit user account with sweeps coins
12        // Update your database
13        // Send confirmation email
14      }}
15      settlementType={SettlementType.USDC}
16      subtotal={{ cents: 300, currency: Currency.USD }}
17      webhookInfo={{
18        itemName: "sword",
19        price: "10.99"
20      }}
21      email="user@email.com"
22      chargebackProtectionData={[{
23        productName: 'Sword',
24        productType: "inGameProduct",
25        quantity: 1,
26        rawProductData: {
27          productID: "sword12345",
28          productDescription: "A legendary sword with magical powers",
29          productCategory: "Weapon"
30        }
31      }]}
32      jwtToken="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
33    />
34  );
35}

Step 6: Customize & Secure

  1. Customize branding
  2. Whitelist your domain

API Implementation

⏱️ Setup time: ~4 hours | Best for: Full control, custom UI

Build a completely custom checkout experience with full control over the UI and flow.

When to Use

  • You need complete control over the checkout UI
  • You want to build a native mobile app experience
  • You have specific business logic requirements

Implementation Steps

Step 1: Share Payer Events

Share key customer lifecycle events to improve approval rates (applicable if using chargeback protection only).

$# Sign Up Event
>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": "therock72",
>    "email": "dwaynejohnson@gmail.com",
>    "firstName": "Dwayne",
>    "lastName": "Johnson"
>  }'
$# Sign In Event
>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": "dwaynejohnson@gmail.com"
>  }'

See all event types →

Step 2: Get Session Key

Generate a JWT token for the customer (valid 24 hours).

$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:

1{
2  "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
3}

Step 3: Get Payment Totals

Show customers a quote including all fees.

$curl --request POST \
>  --url https://api-sandbox.coinflow.cash/api/checkout/totals/merchantId \
>  --header 'accept: application/json' \
>  --header 'content-type: application/json' \
>  --header 'x-coinflow-auth-session-key: YOUR_SESSION_KEY' \
>  --data '{
>    "subtotal": {
>      "cents": 100
>    },
>    "settlementType": "USDC"
>  }'

Response:

1{
2  "card": {
3    "subtotal": { "cents": 100 },
4    "creditCardFees": { "cents": 40 },
5    "chargebackProtectionFees": { "cents": 0 },
6    "gasFees": { "cents": 0 },
7    "total": { "cents": 140 }
8  },
9}

Step 4: Tokenize Card

See PCI-compliant card tokenization guide →

Step 5: Tokenize Checkout Parameters

Encrypt checkout parameters to prevent tampering.

$curl --request POST \
>  --url https://api-sandbox.coinflow.cash/api/checkout/jwt-token \
>  --header 'Authorization: YOUR_API_KEY' \
>  --header 'content-type: application/json' \
>  --data '{
>    "webhookInfo": {
>      "example": "{\"productId\":\"123abc\"}"
>    },
>    "subtotal": {
>      "currency": "USD",
>      "cents": 500
>    },
>    "email": "iamabuyer@gmail.com",
>    "blockchain": "solana",
>    "settlementType": "USDC",
>    "chargebackProtectionData": [{
>      "productName": "shield",
>      "quantity": 1,
>      "productType": "inGameProduct",
>      "rawProductData": {
>        "description": "A shield for in-game use"
>      }
>    }],
>    "supportEmail": "support@mycompany.com"
>  }'

Step 6: Process New Card Checkout

Process a payment for first-time customers.

$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: YOUR_SESSION_KEY' \
>  --header 'x-coinflow-client-ip: 64.227.3.71' \
>  --header 'x-device-id: 123456789' \
>  --data '{
>    "subtotal": {
>      "currency": "USD",
>      "cents": 500
>    },
>    "card": {
>      "cardToken": "411111YJM5TX1111",
>      "expYear": "30",
>      "expMonth": "10",
>      "email": "payer@gmail.com",
>      "firstName": "Dwayne",
>      "lastName": "Johnson",
>      "address1": "380 Prospect Ave",
>      "city": "Brooklyn",
>      "zip": "11215",
>      "state": "NY",
>      "country": "US"
>    },
>    "jwtToken": "YOUR_JWT_TOKEN"
>  }'

Response:

1{
2  "paymentId": "f3fc8a34-680b-4b91-905b-1db5628bbb0e"
3}

Step 7: Process Saved Card Checkout

For returning customers using previously saved cards.

  1. Re-tokenize the saved card with CVV
  2. Call the token checkout endpoint:
$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: YOUR_SESSION_KEY' \
>  --header 'x-coinflow-client-ip: 64.227.3.71' \
>  --header 'x-device-id: 123456789' \
>  --data '{
>    "subtotal": {
>      "currency": "USD",
>      "cents": 500
>    },
>    "jwtToken": "YOUR_JWT_TOKEN",
>    "token": "411111YJM5TX1111"
>  }'

Step 8 (Optional): Retrieve Payment Details

$curl --request GET \
>  --url https://api-sandbox.coinflow.cash/api/merchant/payments/enhanced/PAYMENT_ID \
>  --header 'Authorization: YOUR_API_KEY' \
>  --header 'accept: application/json'

Adding 3DS Authentication (Optional)

Once you’ve completed the basic integration, contact Coinflow to enable 3DS on your account.

Complete 3DS challenge guide →

AI-Powered Chargeback Protection (Optional)

Required Setup

  1. Share payer events (see Step 1 above)

  2. Add the chargeback protection script to every page:

  3. Include additional headers in checkout requests:

    • x-device-id - Obtained after adding the script
    • x-coinflow-client-ip - Payer’s IP address
    • user-agent - Payer’s user agent

  4. Pass chargebackProtectionData in your checkout requests (see Step 5 example)

Next Steps

Now that you’ve chosen your integration method:

  1. Set up webhooks (Required)

    • Receive real-time payment notifications
    • Credit customer accounts with sweeps coins/cash
    • Unlock purchased content or features
    • Update your database with transaction details

  2. Test Your Integration

  3. Go Live

    • Review transactions in your merchant dashboard
    • Contact Coinflow to enable production mode
    • Update to production API endpoints

Support

Need help? Reach out to the Coinflow team or consult the full documentation at docs.coinflow.cash.