nxtpaydocs
Dashboard
Using an AI assistant?Copy the full API spec with instructions, paste it into your AI tool, and it can wire up payments and webhooks for you.
JSON
Get started

Quickstart

Take your first crypto payment in three steps.

  1. Add a payout wallet in Dashboard, Wallet, and create a secret key in Developers.
  2. Create a payment from your server.
  3. Send the customer to url and wait for the payment.paid webhook before you ship.

Authentication

Every request goes to https://api.nxtpay.wtf/v1 over HTTPS with your secret key in the Authorization header. Requests are limited to 10 per second per key.

Header
Authorization: Bearer sk_live_...
Keep it secret. Never put this key in frontend code or a mobile app. Revoke it in Developers if it leaks.

Errors

Errors use normal HTTP status codes and always return an error object.

400 Bad Request
{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_invalid",
    "message": "amount must be a decimal string with up to 2 decimals, e.g. \"49.99\".",
    "param": "amount"
  }
}
StatusTypeMeaning
400invalid_request_errorA parameter is missing or wrong. param says which.
401authentication_errorNo key, or the key is wrong or revoked.
403permission_errorThe account is suspended. The message says why and until when.
404invalid_request_errorNo such payment (or it belongs to another account).
409invalid_request_errorThe payment is no longer in a state that allows this.
429rate_limit_errorToo many requests. Back off and retry.
5xxapi_errorSomething broke on our side. Safe to retry with the same Idempotency-Key.

Fees

The fee is taken from each payment before it's split to your wallets. You always get the lowest rate you qualify for. Network fees for forwarding are paid from the forwarded amount.

RateWhen
2%New accounts.
1.5%After $10,000 in total sales.
1%In any calendar month with $50,000+ in sales.
Payments

The payment object

FieldDescription
idPayment ID, see format.
statusSee statuses.
amount, currencyPrice as a string, e.g. "49.99", and USD or EUR.
description, order_id, metadataWhat you sent. metadata is always an object.
coinsCoins the customer can pick from.
coin, networkWhat the customer picked, once they did. null before.
address, crypto_amountOne-time deposit address and the exact amount to send.
amount_received, tx_hash, confirmationsFilled in when the transaction shows up.
fee_percentOur fee for this payment, set when it's paid.
urlThe payment page. Send your customer here.
success_url, cancel_url, webhook_urlWhat you sent, or null.
created, expires_at, paid_at, canceled_atUnix timestamps in seconds.

Create a payment

POST/v1/payments

Send JSON or form-encoded parameters. The customer picks a coin on the payment page, unless you lock one with coin. Add an Idempotency-Key header (for example your order ID) so a retry never creates a second payment.

ParameterDescription
amountrequiredPrice as a string with up to 2 decimals, from "1.00" to "100000.00". Leave it out when every item in items has a price: the total is used.
currencyrequiredUSD or EUR.
descriptionShown to the customer. Up to 255 characters.
itemsWhat the customer is buying, shown on the payment page instead of one "Payment" line. Up to 20 of { name, quantity, amount, image_url }: name up to 120 characters, quantity 1 to 9999 (default 1), amount the unit price (give it for every item or for none), image_url an HTTPS link to a picture. Form encoding: items[0][name]=Hoodie.
order_idYour own reference, returned everywhere. Up to 100 characters.
success_urlWhere we send the customer after the payment is confirmed. HTTPS.
cancel_urlWhere the "back to shop" links go. HTTPS.
webhook_urlSend this payment's events here instead of your account's webhook URL.
metadataUp to 20 string key/value pairs, e.g. metadata[user_id]=42.
coinsLimit the choice, e.g. ["LTC","USDT_SOL"]. Defaults to every coin. Coins without a payout wallet collect in your balance until you add one.
coinLock to one coin. The response then already has address and crypto_amount.
expires_inSeconds until the payment expires. Default 3600 (1 hour), max 7 days.
curl https://api.nxtpay.wtf/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: order_8812" \
  -d amount=49.99 \
  -d currency=USD \
  -d description="Pro plan" \
  -d order_id=8812 \
  -d success_url=https://shop.example/thanks \
  -d cancel_url=https://shop.example/cart \
  -d "metadata[user_id]=42"
const res = await fetch("https://api.nxtpay.wtf/v1/payments", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.NXTPAY_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "order_8812",
  },
  body: JSON.stringify({
    amount: "49.99", currency: "USD", description: "Pro plan", order_id: "8812",
    items: [{ name: "Pro plan", quantity: 1, amount: "49.99", image_url: "https://shop.example/pro.png" }],
    success_url: "https://shop.example/thanks", cancel_url: "https://shop.example/cart",
    metadata: { user_id: "42" },
  }),
});
const payment = await res.json();
// redirect the customer to payment.url
$ch = curl_init('https://api.nxtpay.wtf/v1/payments');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NXTPAY_KEY'), 'Idempotency-Key: order_8812'],
  CURLOPT_POSTFIELDS => http_build_query([
    'amount' => '49.99', 'currency' => 'USD', 'order_id' => '8812',
    'success_url' => 'https://shop.example/thanks',
    'metadata' => ['user_id' => '42'],
  ]),
]);
$payment = json_decode(curl_exec($ch), true);
header('Location: ' . $payment['url']);
import os, requests

payment = requests.post(
    "https://api.nxtpay.wtf/v1/payments",
    headers={"Authorization": "Bearer " + os.environ["NXTPAY_KEY"], "Idempotency-Key": "order_8812"},
    json={"amount": "49.99", "currency": "USD", "order_id": "8812",
          "success_url": "https://shop.example/thanks", "metadata": {"user_id": "42"}},
).json()

Response

201 Created
{
  "id": "NXT-20261117-482910375-3f2b8c1e-9a4d-4e7b-b2c1-7d5e8f9a0b12-918273645",
  "object": "payment",
  "livemode": true,
  "status": "awaiting_coin",
  "amount": "49.99",
  "currency": "USD",
  "description": "Pro plan",
  "order_id": "8812",
  "metadata": { "user_id": "42" },
  "items": [{ "name": "Pro plan", "quantity": 1, "amount": "49.99", "image_url": "https://shop.example/pro.png" }],
  "coins": ["USDT_SOL", "LTC"],
  "coin": null,
  "network": null,
  "address": null,
  "crypto_amount": null,
  "amount_received": null,
  "tx_hash": null,
  "confirmations": 0,
  "fee_percent": null,
  "url": "https://pay.nxtpay.wtf/NXT-20261117-…",
  "success_url": "https://shop.example/thanks",
  "cancel_url": "https://shop.example/cart",
  "webhook_url": null,
  "created": 1763400000,
  "expires_at": 1763403600,
  "paid_at": null,
  "canceled_at": null
}

Retrieve a payment

GET/v1/payments/:id

Returns the payment object. Use it to double-check a webhook before you ship.

List payments

GET/v1/payments

Newest first. limit 1 to 100 (default 10), starting_after a payment ID to get the next page, status to filter. Returns { "object": "list", "data": [...], "has_more": true }.

Extend a payment

POST/v1/payments/:id/extend

Keeps an open payment alive longer, or reopens an expired one where nothing was paid. seconds defaults to 3600. A payment can stay open up to 7 days after it was created. Also available in the dashboard.

Cancel a payment

POST/v1/payments/:id/cancel

Works while nothing has been paid. The payment page then shows "Payment canceled" and a payment.canceled event is sent.

Statuses

awaiting_coinCreated. The customer hasn't picked a coin yet.
awaiting_paymentAddress generated, waiting for the transaction.
confirmingTransaction seen, waiting for confirmations.
paidConfirmed. Webhook sent. Safe to ship.
underpaidLess than the full amount arrived before expiry. The checkout asks the customer for the rest at the same address; if it arrives, the payment becomes paid.
expiredNothing arrived within the payment window (1 hour unless extended).
canceledYou canceled it.

Payment ID

Every ID has the same shape: date, 9 random digits, your account ID, 9 random digits.

Format
NXT-YYYYMMDD-#########-ACCOUNT-UUID-#########
NXT-20261117-482910375-3f2b8c1e-9a4d-4e7b-b2c1-7d5e8f9a0b12-918273645
Webhooks

Events

We POST JSON to the payment's webhook_url, or to your account's webhook URL. Reply with any 2xx within 10 seconds. Otherwise we retry after 30s, 2m, 10m, 30m, 1h, 2h, 4h and 8h. Webhook URLs must be public HTTPS addresses.

payment.paidThe payment is confirmed. Fulfil the order.
payment.expiredNothing arrived in time.
payment.underpaidThe window closed with only part of the amount. What arrived is still settled to you; amount_received says how much. If the customer sends the rest to the same address, payment.paid follows.
payment.canceledYou canceled it.
testSent from Dashboard, Developers.
POST your webhook URL
{
  "id": "evt_Qm9yZ2V0IGl0IGFscmVhZHk",
  "object": "event",
  "type": "payment.paid",
  "created": 1763400912,
  "data": { "object": { /* the payment object */ } }
}
Events can repeat. Use the event id (or the payment id) to make sure you ship once.

Verify signature

Each request has a NxtPay-Signature header: t=timestamp,v1=hmac. Compute HMAC-SHA256 of t + "." + raw_body with your signing secret (Developers) and compare in constant time. Reject timestamps older than 5 minutes.

import crypto from "node:crypto";

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const mac = crypto.createHmac("sha256", secret).update(parts.t + "." + rawBody).digest("hex");
  return mac.length === parts.v1.length && crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(parts.v1));
}
function nxtpay_verify($raw, $header, $secret) {
  parse_str(str_replace(',', '&', $header), $p);
  if (abs(time() - (int)$p['t']) > 300) return false;
  $mac = hash_hmac('sha256', $p['t'] . '.' . $raw, $secret);
  return hash_equals($mac, $p['v1'] ?? '');
}
import hmac, hashlib, time

def verify(raw: bytes, header: str, secret: str) -> bool:
    p = dict(x.split("=", 1) for x in header.split(","))
    if abs(time.time() - int(p["t"])) > 300:
        return False
    mac = hmac.new(secret.encode(), p["t"].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, p.get("v1", ""))
Testing

Sandbox

Create a test key (sk_test_…) in Developers. Everything it creates is a test payment: livemode is false, the deposit address is a placeholder no wallet accepts, nothing is watched on chain and nothing reaches your balance. Test and live keys never see each other's payments. Webhooks go to the same endpoint with "livemode": false in the payment object, so check it before you ship anything.

No code yet? Switch on Test mode in the dashboard: New payment then creates test payments, and their checkout shows buttons to finish them as paid, underpaid or expired.

Simulate a payment

POST/v1/payments/:id/simulate

Finishes a test payment the way the blockchain would and sends the matching webhook. Test keys only. outcome is paid (default), underpaid or expired. If no coin was picked yet, the first one offered is used.

curl
curl https://api.nxtpay.wtf/v1/payments/NXT-…/simulate \
  -H "Authorization: Bearer sk_test_..." \
  -d outcome=paid
Checkout

Redirects

When the payment is confirmed the payment page shows a receipt and sends the customer to success_url after 5 seconds. "Back to shop" links use cancel_url. The redirect is a convenience: always rely on the webhook (or retrieve the payment) to fulfil orders.

Embed

Open the payment page in an overlay on your site instead of redirecting. Put the payment's url (from the create response) in data-nxtpay, or call NxtPay.open(url) from your own code.

HTML
<script src="https://pay.nxtpay.wtf/embed.js" defer></script>
<button data-nxtpay="https://pay.nxtpay.wtf/NXT-20261117-…">Pay with crypto</button>

Supported coins

CodeNetworkConfirmations
USDT_ETHTether on Ethereum12
USDT_SOLTether on SolanaFinalized
USDT_BSCTether on BNB Chain15
USDC_SOLUSD Coin on SolanaFinalized
USDC_BSCUSD Coin on BNB Chain15
BTCBitcoin on Bitcoin2
LTCLitecoin on Litecoin3
DOGEDogecoin on Dogecoin6
ETHEthereum on Ethereum12
BNBBNB on BNB Chain15
SOLSolana on SolanaFinalized
TRXTron on Tron20
XMRMonero on Monero10