> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexapay.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Crypto Payments

> Accept USDT on TRC20, track merchant crypto payment sessions, and manage USDT balances

# 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

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

### Curl Example

```bash theme={null}
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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "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.