# Quickstart #### 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: ```bash 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): ```bash 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: ```json { "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: ```python 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.