🚀Quickstart

Quick start guide for Nord PAY API

1. General Information

Nord PAY provides a REST‑API for receiving cryptocurrency payments and managing wallets. All methods use the base URL https://api.nord-pay.com/ and accept/return data in JSON format. For authentication, include the X‑API‑KEY header with your API key in every request. For proper handling, also send the header Content‑Type: application/json.

To obtain an API key, register on the NordPay platform and create a project. Without a valid key, most methods will return error 401 or 422.

2. View Available Currencies and Networks

Before creating invoices, review the supported tokens and networks. Use:

• List currencies: GET /currencies/ — returns the full list of available currencies. The response includes the token name (e.g., USDTBEP20), its ticker (USDT), the network (BEP20, ERC20, TRC20, etc.), the contract address (for tokens), decimals, the number of required confirmations, the network fee, the minimum deposit, the minimum withdrawal amount, availability flags for deposits/withdrawals, and the currency’s exchange rate.

• Get rates: GET /currencies/rates — returns current exchange rates of supported currencies against USDT. The rate field shows the token‑to‑USDT ratio.

Example cURL request for the currency list:

curl -X GET "https://api.nord-pay.com/currencies/"
    -H "Content-Type: application/json"

3. Creating an Invoice

To accept crypto, create an invoice via POST /invoice/create. In the request body provide:

Field	Type	Description
currency	string	Invoice currency, e.g. USDTBEP20. If you want to lock the invoice to a single currency, set this parameter and do not set allowed_currencies.
allowed_currencies	array of strings	Alternative currencies that will be accepted. Use this if you want to allow payment in multiple tokens (then currency must be null).
amount	string	Invoice amount. Expressions like 200 USD or 0.015 BNB are allowed.
expires_time	number	Invoice lifetime in minutes (from 30 to 1440).
label	string	Your order identifier for convenient display.
postback_url	string (optional)	Your server URL to receive notifications about payments and invoice expiration.
success_url	string (optional)	URL to redirect the client to after a successful payment.
fail_url	string (optional)	URL to redirect the client to after an error or expiration.

Important: do not send both currency and allowed_currencies — you must use only one of these parameters.

Example request (cURL):

curl -X POST "https://api.nord-pay.com/invoice/create"
     -H "Content-Type: application/json"
     -H "X-API-KEY: YOUR_API_KEY"
     -d '{
       "currency": "USDTBEP20",
       "amount": "200 USD",
       "expires_time": 1,
       "label": "Order #123",
       "postback_url": "https://example.com/postback",
       "success_url": "https://example.com/success"
     }'

The response contains the invoice identifier (id and uuid), the amount, and the payment address. You can show the generated URL to the client for payment.

4. Viewing Invoices and Their Transactions

• List invoices: GET /invoice/ — returns all invoices created for your project. Requires the X‑API‑KEY header.

• Invoice details: GET /invoice/{identifier} — where identifier can be the invoice id or uuid. The response includes the currency, address, and status (paid / expired).

• All invoice transactions: GET /invoice/transactions — you can pass start_date and/or end_date (ISO 8601 or YYYY-MM-DD) to filter by period.

• Transactions for a specific invoice: GET /invoice/{identifier}/transactions — similarly supports start_date and end_date.

All requests return an array of transaction objects with payment information, amount, fees, and status.

5. Wallet Management

Nord PAY lets you create permanent cryptocurrency wallets to receive payments without tying funds to a particular invoice.

• List wallets: GET /wallet/ — returns all wallets for your project.

• Wallet details: GET /wallet/{id} — returns information for a specific wallet (label, address, currency, and timestamps).

• Create a wallet: POST /wallet/create — creates a new wallet. The request body must include currency and label; you can optionally add postback_url.

• Get a QR code: GET /wallet/{id}/qrcode — returns JSON with a qrcode field: a base64‑encoded QR image that you can show to clients for convenient payments.

• Wallet transactions:

  • GET /wallet/transactions — transactions for all wallets with optional start_date and end_date parameters.

  • GET /wallet/{id}/transactions — transactions for a single wallet with the same parameters.

6. Balance and Withdrawals

• Balances: GET /balance/ — returns current balances for each token on your account.

• Withdrawals:

  1. Create a withdrawal request: POST /balance/withdraw/request — accepts currency, address, and amount and returns an identifier (the unique request ID).

  2. Confirm the withdrawal: POST /balance/withdraw/confirm — requires only the identifier and finalizes the transfer. If there are sufficient funds and the request is valid, the response will include a status and, after processing, the transaction hash.

• Batch (multiple) withdrawals:

  1. Create a batch request: POST /balance/withdraw/multiple/request — besides currency, provide an array addresses_and_amounts with address/amount pairs. The response returns an identifier along with information about totals and fees.

  2. Confirm the batch: POST /balance/withdraw/multiple/confirm — accepts the identifier and confirms the batch transfer.

7. Configuring Postback (Webhooks)

To automatically receive payment notifications, specify the postback_url when creating an invoice or wallet. After each confirmed transaction, Nord PAY will send a POST request to your URL with the following structure:

{
  "postback_secret": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "postback_type": "transaction",
  "tx_id": 67890,
  "tx_hash": "abcdef1234567890",
  "tx_type": "invoice",
  "label": "Order #1234",
  "currency": "USDTBEP20",
  "amount": 1000.00,
  "amount_usd": 1000.00,
  "network_fee": 0.00,
  "network_fee_usd": 0.00,
  "service_fee": 5.00,
  "service_fee_usd": 5.00,
  "received_amount": 500.00,
  "received_amount_usd": 500.00,
  "status": "paid",
  "created_at": "2025-05-24T15:00:00Z"
}

The postback_secret is your secret key used to verify the authenticity of the request. You can obtain it in your Nord PAY account profile. Check that the received postback_secret matches your value and remove it from the object before further processing. The payload includes all key transaction data, including its ID, hash, type (invoice / wallet), currency, amount, fees, and status.

Example postback handler in Flask:

from flask import Flask, request, jsonify, abort
import os

app = Flask(__name__)
POSTBACK_SECRET = os.environ.get("POSTBACK_SECRET")

@app.route('/postback', methods=['POST'])
def postback():
    data = request.get_json()
    # Verify secret
    if data.get("postback_secret") != POSTBACK_SECRET:
        abort(401)
    data.pop("postback_secret", None)
    # TODO: handle the transaction data (save to DB, confirm order, etc.)
    return jsonify({"status": "ok"}), 200

8. Testing the Integration

1. Obtain an API key and run the test request GET /currencies/ — make sure you receive the currency list.

2. Create a small test invoice and pay it. After payment, check the status via GET /invoice/{identifier}.

3. Configure a postback and verify that your server receives notifications.

By following these steps, you can integrate Nord PAY into your application and start accepting cryptocurrency payments.