CheckoutImplementation OverviewImplementation Guides

One-Time Purchase Integration

Accept one-time card payments and settle the proceeds to your Coinflow Wallet

This guide walks you through integrating Coinflow’s checkout to accept one-time card purchases. Funds settle to your Coinflow Wallet by default. Choose from three implementation methods.

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

Confirm your settlement location

By default, funds settle to your Coinflow Wallet — managed by Coinflow, no additional setup required.

If you want to settle directly to a destination you control, see Settlement Locations for the available options.

Quick Reference

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

Choose Your Implementation

Best for React applications. Provides a pre-built checkout component.

Step 1: Install the SDK

$npm install @coinflowlabs/react

Step 2: Generate a session key

Create a JWT token to authorize the payer. Call this from your backend.

GET
/api/auth/session-key
1curl https://api-sandbox.coinflow.cash/api/auth/session-key \
2     -H "x-coinflow-auth-user-id: <apiKey>" \
3     -H "Content-Type: application/json"
Try it
Response
1{
2  "key": "a1b2c3d4e5f67890abcdef1234567890"
3}

Session keys expire after 24 hours. Refresh them before expiration.

Step 3: Tokenize checkout parameters

Encrypt checkout parameters to prevent tampering. Call this from your backend.

POST
/api/checkout/jwt-token
1curl -X POST https://api-sandbox.coinflow.cash/api/checkout/jwt-token \
2     -H "Authorization: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{}'
Try it
Response
1{}

Step 4: Render the checkout component

1import { CoinflowPurchase, Currency } from '@coinflowlabs/react';
2
3function Checkout() {
4  return (
5    <CoinflowPurchase
6      merchantId="your-merchant-id"
7      env="sandbox"
8      sessionKey="SESSION_KEY_FROM_STEP_2"
9      jwtToken="JWT_TOKEN_FROM_STEP_3"
10      subtotal={{ cents: 500, currency: Currency.USD }}
11      email="customer@example.com"
12      webhookInfo={{
13        itemName: "sword",
14        price: "10.99"
15      }}
16      chargebackProtectionData={[{
17        productName: 'Sword',
18        productType: 'inGameProduct',
19        quantity: 1,
20        rawProductData: {
21          productID: "sword12345",
22          productDescription: "A legendary sword"
23        }
24      }]}
25      onSuccess={(paymentId) => {
26        console.log('Payment successful:', paymentId);
27        // Redirect user to success page
28      }}
29    />
30  );
31}

Step 5: Configure your dashboard

  1. Customize the UI to match your brand from your dashboard
  2. Whitelist your domain to prevent unauthorized embedding

Chargeback Protection

Coinflow handles fraud detection and chargeback indemnification automatically. To enable it, render the <CoinflowPurchaseProtection> component on every page of your site — that’s all you need to do. Coinflow collects the signals it needs from there.

1import { CoinflowPurchaseProtection } from '@coinflowlabs/react';
2
3// Mount on every page of your app
4<CoinflowPurchaseProtection merchantId="your-merchant-id" />

Once the component is mounted, Coinflow handles device fingerprinting, payer scoring, lifecycle event capture, and approval/decline decisions on every transaction. Approved transactions are covered by chargeback indemnification.

For React Native and mobile-app integrations, see the in-depth Implement Chargeback Protection guide.

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