Skip to main content

​
Crypto Payments

NexaPay lets merchants create USDT on TRC20 payment sessions, receive funds into a session-specific payment address, settle those funds into the NexaPay crypto balance flow, and credit the merchant’s USDT balance after settlement succeeds.

​
How It Works

  1. The merchant creates a crypto payment session.
  2. NexaPay provisions a dedicated collection session for that payment.
  3. NexaPay generates a USDT TRC20 deposit address.
  4. The merchant shows that address to the customer.
  5. NexaPay confirms the deposit.
  6. NexaPay settles the session balance into its parent crypto balance flow.
  7. The merchant’s USDT balance is credited only after settlement succeeds.

​
Current Scope

  • Supported asset: USDT
  • Supported network: TRC20
  • One deposit address per payment session
  • Session status is currently consumed by polling the API
  • Merchant outbound crypto webhook events are not yet part of this release

​
Create Crypto Payment Session

POST /business/crypto/payments/create

​
Request Body

{
  "amount": 50,
  "merchantCustomerId": "cust_12345",
  "merchantReference": "order_90881",
  "currency": "usdt",
  "network": "trc20",
  "expiresInMinutes": 60,
  "metadata": {
    "purpose": "wallet_topup",
    "source": "checkout"
  }
}

​
Curl Example

curl -X POST "https://api.nexapay.ng/api/v1/business/crypto/payments/create" \
  -H "Content-Type: application/json" \
  -H "x-api-key: nexa-prod-..." \
  -d '{
      "amount": 50,
    "merchantCustomerId": "cust_12345",
    "merchantReference": "order_90881",
    "currency": "usdt",
    "network": "trc20",
    "expiresInMinutes": 60,
    "metadata": {
      "purpose": "wallet_topup",
      "source": "checkout"
    }
  }'

​
Response (Production)

{
  "success": true,
  "msg": "Crypto payment session created successfully",
  "payment": {
    "paymentId": "bcpay_1747712000000_a1b2c3d4",
      "merchantCustomerId": "cust_12345",
    "merchantReference": "order_90881",
    "currency": "usdt",
    "network": "trc20",
    "amountExpected": 50,
    "amountReceived": 0,
    "amountCredited": 0,
    "depositAddress": "TRON_ADDRESS_HERE",
    "status": "AWAITING_DEPOSIT",
    "txHash": null,
    "expiresAt": "2026-05-19T16:00:00.000Z",
    "environment": "prod",
    "createdAt": "2026-05-19T15:00:00.000Z",
    "updatedAt": "2026-05-19T15:00:00.000Z",
    "metadata": {
      "purpose": "wallet_topup",
      "source": "checkout"
    }
  }
}

​
Response (Test Key)

{
  "success": true,
  "msg": "Test crypto payment session created successfully",
  "payment": {
    "paymentId": "bcpay_1747712000000_a1b2c3d4",
      "merchantCustomerId": "cust_12345",
    "merchantReference": "order_90881",
    "currency": "usdt",
    "network": "trc20",
    "amountExpected": 50,
    "amountReceived": 0,
    "amountCredited": 0,
    "depositAddress": "TTESTADDRESS1234567890ABCDE",
    "status": "AWAITING_DEPOSIT",
    "txHash": null,
    "expiresAt": "2026-05-19T16:00:00.000Z",
    "environment": "test",
    "createdAt": "2026-05-19T15:00:00.000Z",
    "updatedAt": "2026-05-19T15:00:00.000Z",
    "metadata": {
      "purpose": "wallet_topup",
      "source": "checkout",
      "simulated": true
    }
  }
}

​
Get One Crypto Payment Session

GET /business/crypto/payments/:paymentId

​
Example

curl "https://api.nexapay.ng/api/v1/business/crypto/payments/bcpay_1747712000000_a1b2c3d4" \
  -H "x-api-key: nexa-prod-..."

​
List Crypto Payment Sessions

GET /business/crypto/payments

​
Optional Query Parameters

  • status
  • merchantReference
  • merchantCustomerId
  • limit

​
Example

curl "https://api.nexapay.ng/api/v1/business/crypto/payments?status=SETTLED&limit=20" \
  -H "x-api-key: nexa-prod-..."

​
Get Crypto Balances

GET /business/crypto/balances

​
Response

{
  "success": true,
  "balances": {
    "usdtBalance": 1250.5,
    "usdtPendingBalance": 50
  }
}

​
Payment Session Statuses

NexaPay may return statuses such as:
  • INITIATED
  • ADDRESS_PENDING
  • AWAITING_DEPOSIT
  • PENDING_CONFIRMATION
  • SWEEP_PENDING
  • SETTLED
  • UNDERPAID
  • OVERPAID
  • EXPIRED
  • MANUAL_REVIEW
  • FAILED

​
Status Notes

  • SETTLED means the session deposit has already been settled into the merchant’s USDT balance.
  • SWEEP_PENDING means the customer payment has been detected and NexaPay is finalizing internal balance settlement.
  • UNDERPAID, OVERPAID, and MANUAL_REVIEW should be treated as non-final operational states that may require manual handling.

​
Crypto Balance Behaviour

NexaPay maintains a separate merchant USDT balance from the normal NGN business wallet.
  • Fiat merchant deposits and withdrawals affect the NGN wallet.
  • Settled crypto payments affect the USDT wallet.
  • USDT is not withdrawn on-chain to the merchant.
  • When the merchant cashes out USDT, NexaPay converts the selected USDT amount to NGN and settles the NGN equivalent to the merchant’s saved bank account.