Quickstart
Take your first crypto payment in three steps.
- Add a payout wallet in Dashboard, Wallet, and create a secret key in Developers.
- Create a payment from your server.
- Send the customer to
urland wait for thepayment.paidwebhook 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.
Authorization: Bearer sk_live_...
Errors
Errors use normal HTTP status codes and always return an error object.
{
"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"
}
}| Status | Type | Meaning |
|---|---|---|
400 | invalid_request_error | A parameter is missing or wrong. param says which. |
401 | authentication_error | No key, or the key is wrong or revoked. |
403 | permission_error | The account is suspended. The message says why and until when. |
404 | invalid_request_error | No such payment (or it belongs to another account). |
409 | invalid_request_error | The payment is no longer in a state that allows this. |
429 | rate_limit_error | Too many requests. Back off and retry. |
5xx | api_error | Something 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.
| Rate | When |
|---|---|
2% | New accounts. |
1.5% | After $10,000 in total sales. |
1% | In any calendar month with $50,000+ in sales. |
The payment object
| Field | Description |
|---|---|
id | Payment ID, see format. |
status | See statuses. |
amount, currency | Price as a string, e.g. "49.99", and USD or EUR. |
description, order_id, metadata | What you sent. metadata is always an object. |
coins | Coins the customer can pick from. |
coin, network | What the customer picked, once they did. null before. |
address, crypto_amount | One-time deposit address and the exact amount to send. |
amount_received, tx_hash, confirmations | Filled in when the transaction shows up. |
fee_percent | Our fee for this payment, set when it's paid. |
url | The payment page. Send your customer here. |
success_url, cancel_url, webhook_url | What you sent, or null. |
created, expires_at, paid_at, canceled_at | Unix timestamps in seconds. |
Create a payment
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.
| Parameter | Description |
|---|---|
amountrequired | Price 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. |
currencyrequired | USD or EUR. |
description | Shown to the customer. Up to 255 characters. |
items | What 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_id | Your own reference, returned everywhere. Up to 100 characters. |
success_url | Where we send the customer after the payment is confirmed. HTTPS. |
cancel_url | Where the "back to shop" links go. HTTPS. |
webhook_url | Send this payment's events here instead of your account's webhook URL. |
metadata | Up to 20 string key/value pairs, e.g. metadata[user_id]=42. |
coins | Limit the choice, e.g. ["LTC","USDT_SOL"]. Defaults to every coin. Coins without a payout wallet collect in your balance until you add one. |
coin | Lock to one coin. The response then already has address and crypto_amount. |
expires_in | Seconds 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
{
"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
Returns the payment object. Use it to double-check a webhook before you ship.
List 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
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
Works while nothing has been paid. The payment page then shows "Payment canceled" and a payment.canceled event is sent.
Statuses
awaiting_coin | Created. The customer hasn't picked a coin yet. |
awaiting_payment | Address generated, waiting for the transaction. |
confirming | Transaction seen, waiting for confirmations. |
paid | Confirmed. Webhook sent. Safe to ship. |
underpaid | Less 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. |
expired | Nothing arrived within the payment window (1 hour unless extended). |
canceled | You canceled it. |
Payment ID
Every ID has the same shape: date, 9 random digits, your account ID, 9 random digits.
NXT-YYYYMMDD-#########-ACCOUNT-UUID-######### NXT-20261117-482910375-3f2b8c1e-9a4d-4e7b-b2c1-7d5e8f9a0b12-918273645
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.paid | The payment is confirmed. Fulfil the order. |
payment.expired | Nothing arrived in time. |
payment.underpaid | The 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.canceled | You canceled it. |
test | Sent from Dashboard, Developers. |
{
"id": "evt_Qm9yZ2V0IGl0IGFscmVhZHk",
"object": "event",
"type": "payment.paid",
"created": 1763400912,
"data": { "object": { /* the payment object */ } }
}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", ""))
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
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 https://api.nxtpay.wtf/v1/payments/NXT-…/simulate \ -H "Authorization: Bearer sk_test_..." \ -d outcome=paid
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.
<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
| Code | Network | Confirmations |
|---|---|---|
USDT_ETH | Tether on Ethereum | 12 |
USDT_SOL | Tether on Solana | Finalized |
USDT_BSC | Tether on BNB Chain | 15 |
USDC_SOL | USD Coin on Solana | Finalized |
USDC_BSC | USD Coin on BNB Chain | 15 |
BTC | Bitcoin on Bitcoin | 2 |
LTC | Litecoin on Litecoin | 3 |
DOGE | Dogecoin on Dogecoin | 6 |
ETH | Ethereum on Ethereum | 12 |
BNB | BNB on BNB Chain | 15 |
SOL | Solana on Solana | Finalized |
TRX | Tron on Tron | 20 |
XMR | Monero on Monero | 10 |