CoinFlow Setup Guide

Get started with CoinFlow integration in under 10 minutes.

Prerequisites

A HedgePayments account
Node.js 18+ installed
Basic understanding of React/Next.js

Step 1: Create CoinFlow Account

Visit coinflow.cash
Click “Get Started” or “Sign Up”
Complete the registration form
Verify your email address

Step 2: Get Your Credentials

Sandbox Credentials (for testing)

Log into your CoinFlow dashboard
Navigate to Settings → API Keys
Copy your sandbox credentials:
- Merchant ID
- API Key
- Webhook Secret

Production Credentials (for live payments)

Complete merchant verification (KYC)
Navigate to Settings → API Keys → Production
Generate and copy production credentials

Never commit API keys to version control. Always use environment variables.

Step 3: Configure Environment Variables

Create a .env.local file in your project root:

# CoinFlow Sandbox Configuration
COINFLOW_MERCHANT_ID=your_sandbox_merchant_id
COINFLOW_API_KEY=your_sandbox_api_key
COINFLOW_WEBHOOK_SECRET=your_sandbox_webhook_secret
COINFLOW_ENV=sandbox

# Public keys for client-side
NEXT_PUBLIC_COINFLOW_ENV=sandbox
NEXT_PUBLIC_COINFLOW_MERCHANT_ID=your_sandbox_merchant_id

Step 4: Install Dependencies

Install the CoinFlow React SDK:

npm install @coinflowlabs/react

Or with yarn:

yarn add @coinflowlabs/react

Step 5: Create Payment Component

Create a new component components/CoinflowPayment.tsx:

'use client';

import { CoinflowPurchase } from '@coinflowlabs/react';
import { Connection, clusterApiUrl } from '@solana/web3.js';

export default function CoinflowPayment() {
  const connection = new Connection(clusterApiUrl('devnet'));

  return (
    <div className="max-w-2xl mx-auto p-6">
      <h2 className="text-2xl font-bold mb-6">Complete Payment</h2>

      <CoinflowPurchase
        merchantId={process.env.NEXT_PUBLIC_COINFLOW_MERCHANT_ID!}
        env={process.env.NEXT_PUBLIC_COINFLOW_ENV as 'sandbox' | 'production'}
        connection={connection}
        amount={100.00}
        blockchain="solana"
        onSuccess={(data) => {
          console.log('Payment successful!', data);
          // Handle successful payment
          window.location.href = '/payment-success';
        }}
        onFailure={(error) => {
          console.error('Payment failed:', error);
          // Handle failed payment
        }}
      />
    </div>
  );
}

Step 6: Create API Endpoint

Create an API route app/api/payments/create/route.ts:

import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  try {
    const { amount, currency, customerEmail } = await req.json();

    // Validate input
    if (!amount || !currency || !customerEmail) {
      return NextResponse.json(
        { error: 'Missing required fields' },
        { status: 400 }
      );
    }

    // Create payment record in your database
    const payment = await createPaymentRecord({
      amount,
      currency,
      customerEmail,
      status: 'pending',
      provider: 'coinflow'
    });

    return NextResponse.json({
      success: true,
      paymentId: payment.id
    });

  } catch (error) {
    console.error('Payment creation error:', error);
    return NextResponse.json(
      { error: 'Failed to create payment' },
      { status: 500 }
    );
  }
}

Step 7: Set Up Webhooks

Configure Webhook URL

In your CoinFlow dashboard, go to Settings → Webhooks
Add your webhook URL: https://yourdomain.com/api/webhooks/coinflow
Select events to subscribe to:
- payment.completed
- payment.failed
- payment.refunded

Create Webhook Handler

Create app/api/webhooks/coinflow/route.ts:

import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';

function verifySignature(body: string, signature: string, secret: string) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return hash === signature;
}

export async function POST(req: NextRequest) {
  const body = await req.text();
  const signature = req.headers.get('x-coinflow-signature');

  // Verify webhook signature
  const isValid = verifySignature(
    body,
    signature!,
    process.env.COINFLOW_WEBHOOK_SECRET!
  );

  if (!isValid) {
    return NextResponse.json(
      { error: 'Invalid signature' },
      { status: 401 }
    );
  }

  const event = JSON.parse(body);

  // Handle different event types
  switch (event.type) {
    case 'payment.completed':
      await handlePaymentCompleted(event.data);
      break;
    case 'payment.failed':
      await handlePaymentFailed(event.data);
      break;
    default:
      console.log('Unhandled event:', event.type);
  }

  return NextResponse.json({ received: true });
}

async function handlePaymentCompleted(data: any) {
  // Update payment status in database
  console.log('Payment completed:', data);
  // Send confirmation email
  // Update user's wallet
}

async function handlePaymentFailed(data: any) {
  // Log failed payment
  console.log('Payment failed:', data);
  // Notify user
}

Step 8: Test Your Integration

Using Sandbox

Start your development server:

npm run dev

Navigate to your payment page
Use test credentials:
- Email: test@coinflow.cash
- Card: Any standard test card number

Test Payment Flow

Create a test payment
Complete the CoinFlow widget
Verify webhook is received
Check payment status in database

Step 9: Go to Production

Before Launch Checklist

Complete CoinFlow merchant verification
Switch to production API keys
Update environment variables
Test production webhook endpoint
Set up error monitoring
Configure payment success/failure pages
Review transaction limits

Production Environment

Update your production environment variables:

COINFLOW_ENV=production
COINFLOW_MERCHANT_ID=prod_merchant_id
COINFLOW_API_KEY=prod_api_key
COINFLOW_WEBHOOK_SECRET=prod_webhook_secret

NEXT_PUBLIC_COINFLOW_ENV=production
NEXT_PUBLIC_COINFLOW_MERCHANT_ID=prod_merchant_id

Common Issues

Issue: Widget shows loading spinner indefinitely Solution:

Verify NEXT_PUBLIC_COINFLOW_MERCHANT_ID is set
Check browser console for errors
Ensure environment matches (sandbox/production)

Webhook Not Receiving Events

Issue: Payments succeed but webhooks never arrive Solution:

Verify webhook URL is publicly accessible
Check webhook signature validation logic
Review CoinFlow dashboard webhook logs

CORS Errors

Issue: Cross-origin errors in browser Solution:

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/api/:path*',
        headers: [
          { key: 'Access-Control-Allow-Origin', value: '*' },
          { key: 'Access-Control-Allow-Methods', value: 'GET,POST,OPTIONS' },
        ],
      },
    ];
  },
};

Next Steps

✅ Read the full CoinFlow Integration Guide
✅ Explore the API Reference
✅ Learn about AI Integration
✅ Set up monitoring and analytics

Need Help?

Documentation: docs.coinflow.cash
Email Support: support@hedgepayments.com
Discord Community: discord.gg/hedgepayments
CoinFlow Support: support@coinflow.cash

Integration Guides

CoinFlow Setup

CoinFlow Setup Guide

Prerequisites

Step 1: Create CoinFlow Account

Step 2: Get Your Credentials

Sandbox Credentials (for testing)

Production Credentials (for live payments)

Step 3: Configure Environment Variables

Step 4: Install Dependencies

Step 5: Create Payment Component

Step 6: Create API Endpoint

Step 7: Set Up Webhooks

Configure Webhook URL

Create Webhook Handler

Step 8: Test Your Integration

Using Sandbox

Test Payment Flow

Step 9: Go to Production

Before Launch Checklist

Production Environment

Common Issues

Payment Widget Not Loading

Webhook Not Receiving Events

CORS Errors

Next Steps

Need Help?

​CoinFlow Setup Guide

​Prerequisites

​Step 1: Create CoinFlow Account

​Step 2: Get Your Credentials

​Sandbox Credentials (for testing)

​Production Credentials (for live payments)

​Step 3: Configure Environment Variables

​Step 4: Install Dependencies

​Step 5: Create Payment Component

​Step 6: Create API Endpoint

​Step 7: Set Up Webhooks

​Configure Webhook URL

​Create Webhook Handler

​Step 8: Test Your Integration

​Using Sandbox

​Test Payment Flow

​Step 9: Go to Production

​Before Launch Checklist

​Production Environment

​Common Issues

​Payment Widget Not Loading

​Webhook Not Receiving Events

​CORS Errors

​Next Steps

​Need Help?

CoinFlow Setup Guide

Prerequisites

Step 1: Create CoinFlow Account

Step 2: Get Your Credentials

Sandbox Credentials (for testing)

Production Credentials (for live payments)

Step 3: Configure Environment Variables

Step 4: Install Dependencies

Step 5: Create Payment Component

Step 6: Create API Endpoint

Step 7: Set Up Webhooks

Configure Webhook URL

Create Webhook Handler

Step 8: Test Your Integration

Using Sandbox

Test Payment Flow

Step 9: Go to Production

Before Launch Checklist

Production Environment

Common Issues

Payment Widget Not Loading

Webhook Not Receiving Events

CORS Errors

Next Steps

Need Help?