​
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

​
amount
integer
required
Payment amount in minor units (e.g., cents, kobo)
  • Minimum: 100
  • Must be positive integer
  • Example: 10000 = $100.00 USD
​
currency
string
required
Three-letter ISO currency code
  • Supported: NGN, USD, CAD
  • Must match payment method
  • Example: “USD”
​
customer
object
required
Customer information object
​
description
string
required
Payment description
  • Maximum length: 200 characters
  • Will appear on statements
​
reference
string
required
Unique transaction reference
  • Must be unique per transaction
  • Maximum length: 50 characters
​
payment_method
object
required
Payment method details
​
type
string
required
  • Must be of type: ""
​
order
object
required
Order information object
​
metadata
object
Optional additional data
  • Nested objects allowed

​
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"
    },
    "ip_address": "127.0.0.1"
  },
  "description": "Crypto Payment",
  "currency": "USD",
  "amount": 100000,
  "direction": "incoming",
  "payment_method": {
    "type": "crypto_address"
  },
  "reference": "crypto-tx-123",
  "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",
      "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: