​
Overview

Initialize stablecoin payments using supported tokens across multiple blockchain networks. This endpoint supports both inbound and outbound crypto transactions with real-time rate conversion.

​
Supported Tokens and Chains

USDT

  • Ethereum (ETH)

  • Tron (TRX)

  • BNB Smart Chain (BSC)

USDC

  • Ethereum (ETH)

  • Polygon (MATIC)

  • Avalanche C-Chain (AVAXC)

Ensure you use the correct chain for each token to avoid lost transactions. Not all tokens are supported on all chains.

​
Transaction Limits

  • Minimum: 10 USDT/USDC

  • Maximum: 50,000 USDT/USDC per transaction

Transaction limits may vary based on:

  • Account verification level

  • Transaction history

  • Selected chain/token

​
Processing Times

​
Initialize Payment

POST /payment-sessions

​
Request Parameters

​
customer
object
required

Customer details object

​
currency
string
required

Transaction currency (USD)

​
amount
integer
required

Amount in minor units (cents)

  • Minimum: 1,000 (10 USD)

  • Maximum: 10,000,000 (100,000 USD)

​
direction
string
default:"incoming"
required

Transaction direction: “incoming” or “outgoing”

​
payment_method
object
required
​
reference
string
required

Unique transaction reference

​
metadata
object
required

Additional transaction metadata

​
Request Example

{
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+2348118873422",
    "billing_address": {
      "line1": "123 Main St",
      "line2": "234 Feranmi Drive",
      "city": "Springfield",
      "state": "CA",
      "country": "US",
      "zip_code": "12345"
    }
  },
  "description": "Crypto Payment",
  "currency": "USD",
  "amount": 100000,
  "direction": "incoming",
  "payment_method": {
    "type": "crypto_address"
  },
  "reference": "crypto-tx-123",
  "metadata": {
    "order": {
      "identifier": "ORD12345",
      "items": [
        {
          "name": "Digital Product",
          "type": "digital"
        }
      ]
    }
  }
}

​
Response Example

{
  "data": {
    "status": "pending",
    "message": "Payment session initialized",
    "payment": {
      "id": "pay_123abc456def",
      "currency": "USD",
      "amount": 100000,
      "description": "Crypto Payment",
      "payment_method": {
        "address": "TRWBqiqoFZysoAeyR1J35ibuyc8EvhUAoY",
        "chain": "TRX",
        "currency": "USDT",
        "type": "crypto_address"
      },
      "status": "pending",
      "date": "2024-03-15T12:00:00Z",
      "mode": "live",
      "customer": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "billing_address": {
          "line1": "123 Main St",
          "line2": "234 Feranmi Drive",
          "city": "Springfield",
          "state": "CA",
          "zip_code": "12345",
          "country": "US"
        }
      },
      "reference": "crypto-tx-123",
      "metadata": {
        "order": {
          "identifier": "ORD12345",
          "items": [
            {
              "name": "Digital Product",
              "type": "digital"
            }
          ]
        }
      }
    }
  }
}

​
Validation Rules

​
Rate Conversion

  • Exchange rates are locked for 15 minutes

  • Rates include network fees

  • Rate source: aggregated from major exchanges

  • Rate updates: every 30 seconds

​
Webhooks

Monitor transaction status via webhooks:

  • crypto.payment.pending- Payment detected but unconfirmed

  • crypto.payment.confirmed- Required confirmations reached

  • crypto.payment.completed- Funds credited to account

  • crypto.payment.failed- Transaction failed or expired

​
Best Practices

  1. Security

    • Validate addresses before displaying

    • Show clear network/token warnings

    • Include QR codes for addresses

  2. User Experience

    • Display real-time rate updates

    • Show confirmation progress

    • Provide clear payment instructions

  3. Error Handling

    • Handle network congestion

    • Implement payment expiry

    • Monitor transaction status

Need Help?

For additional assistance: