API Documentation

Complete reference for integrating NovaPayments into your application. All endpoints use HMAC-SHA256 authentication.

Authentication

All API requests must include the following headers:

X-API-Key: sk_live_your_api_key
X-Signature: hmac_sha256(request_body, api_secret)
Content-Type: application/json

The signature is generated by signing the JSON request body with your API secret using HMAC-SHA256. For GET requests without a body, sign an empty string.

Base URL

https://api.novapayments.io

Endpoints

POST/api/v1/deposit/create

Create a new deposit request. Returns a unique crypto address or payment link.

Request Body

{
  "userId": "user_8a2f",
  "amount": 100,
  "currency": "USDT",
  "network": "TRC20"
}

Response

200

{
  "id": "dep_001",
  "depositAddress": "T9f8a2B3c1D4e5F6g7H8i9J0kLm...",
  "network": "TRC20",
  "amount": 100,
  "currency": "USDT",
  "expiresAt": "2025-03-06T01:00:00Z"
}

POST/api/v1/withdraw/create

Create a withdrawal request. Converts internal currency to USDT and sends to user's wallet.

Request Body

{
  "userId": "user_8a2f",
  "amount": 500,
  "walletAddress": "T9f8a2B3c1D4e5F...",
  "network": "TRC20"
}

Response

200

{
  "id": "pay_001",
  "status": "pending_approval",
  "amount": 500,
  "amountUsdt": 470.00,
  "fee": 30.00,
  "networkFee": 1.00
}

GET/api/v1/balance/:userId

Get the current balance for a user.

Response

200

{
  "userId": "user_8a2f",
  "balance": 4520.00,
  "currency": "Stars",
  "updatedAt": "2025-03-06T00:05:00Z"
}

POST/api/v1/transfer

Internal transfer between users (donations, subscriptions, purchases).

Request Body

{
  "fromUserId": "user_3b1c",
  "toUserId": "user_8a2f",
  "amount": 50,
  "description": "Donation",
  "metadata": { "streamId": "stream_123" }
}

Response

200

{
  "id": "tx_001",
  "status": "completed",
  "amount": 50,
  "fromBalance": 1180.50,
  "toBalance": 4570.00
}

GET/api/v1/transactions

Get transaction history with pagination and filters.

Response

200

{
  "data": [
    {
      "id": "tx_001",
      "type": "transfer",
      "amount": 50,
      "balanceBefore": 4520.00,
      "balanceAfter": 4570.00,
      "createdAt": "2025-03-05T22:30:00Z"
    }
  ],
  "total": 156,
  "page": 1,
  "limit": 20
}

Webhook Events

Configure webhook endpoints to receive real-time notifications about payment events.

deposit.confirmedA deposit has been confirmed on the blockchain

deposit.failedA deposit has failed or expired

payout.completedA payout has been successfully sent

payout.failedA payout has failed

transfer.completedAn internal transfer has been completed

Webhook Payload Example

{
  "event": "deposit.confirmed",
  "data": {
    "id": "dep_001",
    "userId": "user_8a2f",
    "amount": 100,
    "currency": "USDT",
    "network": "TRC20",
    "txHash": "T9f8a2...3b1c",
    "confirmations": 20
  },
  "timestamp": "2025-03-06T00:05:00Z",
  "signature": "hmac_sha256_of_payload"
}

Error Codes

Code	Description
400	Bad Request — Invalid parameters
401	Unauthorized — Invalid API key or signature
403	Forbidden — IP not whitelisted
404	Not Found — Resource doesn't exist
409	Conflict — Duplicate transaction (idempotency)
429	Too Many Requests — Rate limit exceeded
500	Server Error — Something went wrong