Quick Start Guide

This guide will help you integrate Cryptofuse API into your application with a focus on ERC20 token payments on EVM-compatible networks.

Prerequisites

Before you begin, ensure you have:

A Cryptofuse merchant account
OAuth2 client credentials (client ID and client secret)
Basic understanding of RESTful APIs
A server-side application (never expose credentials in client-side code)

Step 1: Authentication

Cryptofuse uses OAuth 2.0 with the client credentials flow for secure API access.

Getting an Access Token

Request an access token using your client credentials:

# Create base64 encoded credentials
CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
CREDENTIALS=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64)

# Request access token
curl -X POST https://api.cryptofuse.io/o/token/ \
  -H "Authorization: Basic $CREDENTIALS" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=read write"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Using the Access Token

Include the access token in all API requests:

Authorization: Bearer your_access_token_here

Step 2: Create a Payment

Create a payment request for USDTERC20 (Tether USD on Ethereum):

curl -X POST https://api.cryptofuse.io/payments/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "price_amount": 100.00,
    "price_currency": "USD",
    "pay_currency": "USDTERC20",
    "order_id": "ORDER-12345",
    "order_description": "Premium subscription payment",
    "callback_url": "https://your-site.com/webhook/payment"
  }'

Alternative: Using Blockchain + Token

You can also specify the blockchain and token separately:

{
  "price_amount": 100.00,
  "price_currency": "USD",
  "blockchain": "ethereum",
  "token": "USDT",
  "order_id": "ORDER-12345"
}

Payment Response

{
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "waiting",
  "price_amount": "100.00",
  "price_currency": "USD",
  "pay_amount": "100.050000",
  "pay_currency": "USDTERC20",
  "blockchain_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8b8E0",
  "blockchain_network": "ETH",
  "token": "USDT",
  "expiry_time": "2025-01-15T10:30:00Z",
  "order_id": "ORDER-12345",
  "created_at": "2025-01-15T10:00:00Z"
}

Important Fields

transaction_id: Unique payment identifier (store this!)
blockchain_address: EVM address where customer sends payment
pay_amount: Exact amount customer must send
expiry_time: Payment deadline (default: 30 minutes)

Step 3: Display Payment Information

Show your customer:

Payment address: 0x742d35Cc6634C0532925a3b844Bc9e7595f8b8E0
Amount to send: 100.050000 USDT
Network: Ethereum (ERC20)
Time limit: 30 minutes

QR Code Generation

Generate a QR code for easy mobile payments:

// Example using qrcode.js
const paymentData = `ethereum:${address}?value=${amount}`;
QRCode.toDataURL(paymentData, (err, url) => {
  // Display QR code image
});

Step 4: Monitor Payment Status

Check payment status regularly or wait for webhook notifications:

curl -X GET https://api.cryptofuse.io/payments/550e8400-e29b-41d4-a716-446655440000/ \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Status Response

{
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "confirming",
  "payment_type": "full",
  "transaction_hash": "0x123abc456def...",
  "confirmations": 3,
  "payment_history": [
    {
      "deposit_id": "dep_123",
      "amount": "100.050000",
      "transaction_hash": "0x123abc456def...",
      "confirmations": 3,
      "timestamp": "2025-01-15T10:15:00Z"
    }
  ],
  "merchant_received_usd": "99.00",
  "updated_at": "2025-01-15T10:15:30Z"
}

Payment Statuses

waiting: Awaiting payment
confirming: Payment received, confirming on blockchain
confirmed: Payment confirmed
completed: Payment processed and credited
expired: Payment window expired
failed: Payment failed

Step 5: Handle Webhook Notifications

Cryptofuse sends real-time updates to your callback_url:

Webhook Payload

{
  "event": "payment_status_update",
  "data": {
    "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "payment_type": "full",
    "order_id": "ORDER-12345",
    "merchant_received_usd": "99.00",
    "payment_history": [...],
    "metadata": {
      "updated_at": "2025-01-15T10:20:00Z"
    }
  },
  "timestamp": "2025-01-15T10:20:00Z"
}

Webhook Verification

Verify webhook authenticity using HMAC-SHA256:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# In your webhook handler
signature = request.headers.get('X-Cryptofuse-Signature')
if verify_webhook(request.body, signature, webhook_secret):
    # Process webhook

Webhook Response

Always respond with 200 OK:

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "received"}

Step 6: Create a Withdrawal

Withdraw funds to an EVM address:

curl -X POST https://api.cryptofuse.io/withdrawal/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "currency": "USDTERC20",
    "address": "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE",
    "custom_id": "WITHDRAW-001"
  }'

Withdrawal Response

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "amount": "50.00",
  "currency": "USDTERC20",
  "address": "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE",
  "network_fee": "2.50",
  "total_deducted": "52.50",
  "custom_id": "WITHDRAW-001",
  "created_at": "2025-01-15T11:00:00Z"
}

Example Integration (Node.js)

const axios = require('axios');

class CryptofuseClient {
  constructor(clientId, clientSecret) {
    this.baseURL = 'https://api.cryptofuse.io';
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.accessToken = null;
  }

  async authenticate() {
    const credentials = Buffer.from(`${this.clientId}:${this.clientSecret}`).toString('base64');
    
    const response = await axios.post(`${this.baseURL}/o/token/`, 
      'grant_type=client_credentials&scope=read write',
      {
        headers: {
          'Authorization': `Basic ${credentials}`,
          'Content-Type': 'application/x-www-form-urlencoded'
        }
      }
    );
    
    this.accessToken = response.data.access_token;
    return this.accessToken;
  }

  async createPayment(amount, orderId) {
    const response = await axios.post(`${this.baseURL}/payments/`, {
      price_amount: amount,
      price_currency: 'USD',
      pay_currency: 'USDTERC20',
      order_id: orderId,
      callback_url: 'https://your-site.com/webhook/payment'
    }, {
      headers: {
        'Authorization': `Bearer ${this.accessToken}`,
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  }

  async getPaymentStatus(transactionId) {
    const response = await axios.get(
      `${this.baseURL}/payments/${transactionId}/`,
      {
        headers: {
          'Authorization': `Bearer ${this.accessToken}`
        }
      }
    );
    
    return response.data;
  }
}

// Usage
const client = new CryptofuseClient('your_client_id', 'your_client_secret');

async function processPayment() {
  // Authenticate
  await client.authenticate();
  
  // Create payment
  const payment = await client.createPayment(100.00, 'ORDER-12345');
  console.log('Payment address:', payment.blockchain_address);
  console.log('Amount to pay:', payment.pay_amount, payment.pay_currency);
  
  // Check status
  const status = await client.getPaymentStatus(payment.transaction_id);
  console.log('Payment status:', status.status);
}

Best Practices

Security

Never expose credentials in client-side code
Verify webhooks using HMAC signatures
Use HTTPS for all API calls and callbacks
Store sensitive data securely (encrypted)

Error Handling

Implement retry logic for network failures
Handle all possible payment statuses
Log errors for debugging
Provide clear user feedback

Testing

Use staging environment for development
Test with small amounts first
Simulate different payment scenarios
Test webhook handling thoroughly

Common Integration Patterns

E-commerce Checkout

Create payment when order is placed
Display payment details to customer
Monitor status via webhooks
Update order status on completion

Subscription Services

Create recurring payment requests
Send payment reminders before expiry
Auto-suspend on payment failure
Reactivate on successful payment

Gaming/iGaming Deposits

Create payment for deposit amount
Show in-app payment dialog
Credit user balance on completion
Enable instant gameplay

Next Steps

Need Help?

Email: [email protected]
Documentation: https://docs.cryptofuse.io
API Status: https://status.cryptofuse.io

Our support team is ready to assist with your integration!

Prerequisites​

Step 1: Authentication​

Getting an Access Token​

Using the Access Token​

Step 2: Create a Payment​

Alternative: Using Blockchain + Token​

Payment Response​

Important Fields​

Step 3: Display Payment Information​

QR Code Generation​

Step 4: Monitor Payment Status​

Status Response​

Payment Statuses​

Step 5: Handle Webhook Notifications​

Webhook Payload​

Webhook Verification​

Webhook Response​

Step 6: Create a Withdrawal​

Withdrawal Response​

Example Integration (Node.js)​

Best Practices​

Security​

Error Handling​

Testing​

Common Integration Patterns​

E-commerce Checkout​

Subscription Services​

Gaming/iGaming Deposits​

Next Steps​

Need Help?​