​
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"
    }
  },
  "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: