{"$schema":"https://json-schema.org/draft/2020-12/schema","name":"nxtpay","version":"v1","spec_url":"https://docs.nxtpay.wtf/nxtpay-ai.json","instructions_for_ai":["You are integrating nxtpay crypto payments into the user's application. Ask which language/framework they use if it isn't clear from their code.","Store the secret key (sk_live_...) in an environment variable named NXTPAY_KEY and the webhook signing secret (whsec_...) in NXTPAY_WEBHOOK_SECRET. Never expose either to the browser or commit them.","Checkout flow: on the server create a payment with POST /v1/payments, save payment.id next to the order, then redirect the customer to payment.url (or open it with the embed script).","Always send an Idempotency-Key header (use the order ID) so retries never create two payments.","Fulfil the order ONLY after receiving the payment.paid webhook with a valid NxtPay-Signature, or after GET /v1/payments/:id returns status 'paid'. Never trust the success_url redirect alone.","Make the webhook handler idempotent: the same event can arrive more than once. Respond 2xx within 10 seconds and do slow work afterwards.","Verify the webhook signature over the RAW request body (before JSON parsing) exactly as described in webhooks.signature.","Amounts are decimal strings in fiat (\"49.99\"), not cents.","Handle payment.expired and payment.canceled by releasing reserved stock / marking the order unpaid. Handle payment.underpaid by flagging the order for review (part of the money arrived). A late payment can still turn an expired payment into paid: always trust the latest event.","Add basic error handling: non-2xx responses return { error: { type, code, message, param } }.","Develop against the sandbox: a sk_test_ key creates test payments (livemode false, fake addresses, no money). Finish them with POST /v1/payments/{id}/simulate and check your webhook. In production ignore events whose payment has livemode false."],"base_url":"https://api.nxtpay.wtf/v1","authentication":{"type":"bearer","header":"Authorization","format":"Bearer sk_live_...","where_to_get":"https://dash.nxtpay.wtf/developers"},"request_format":"application/json or application/x-www-form-urlencoded (form: metadata[key]=value, coins[]=LTC)","rate_limit":"10 requests per second per key; 429 when exceeded","idempotency":{"header":"Idempotency-Key","description":"Up to 255 chars. Same key returns the same payment instead of creating a new one."},"endpoints":[{"method":"POST","path":"/payments","summary":"Create a payment","params":{"amount":{"type":"string","required":true,"example":"49.99","rules":"decimal with up to 2 places, 1.00 to 100000.00; may be omitted when every item has an amount (total is used); if given with priced items it must equal their total"},"currency":{"type":"string","required":true,"enum":["USD","EUR"]},"description":{"type":"string","max":255,"note":"shown to the customer"},"items":{"type":"array","max":20,"items":{"name":"string, required, max 120","quantity":"integer 1-9999, default 1","amount":"string unit price, all items or none","image_url":"https URL, max 500"},"note":"line items shown on the payment page; form encoding items[0][name]=..."},"order_id":{"type":"string","max":100,"note":"your reference, returned everywhere"},"brand":{"type":"string","note":"one of the merchant's sales names (Dashboard > Settings); defaults to the default name"},"success_url":{"type":"string","format":"https URL","note":"customer is sent here after payment is confirmed"},"cancel_url":{"type":"string","format":"https URL","note":"'back to shop' links"},"webhook_url":{"type":"string","format":"public https URL","note":"overrides the account webhook URL for this payment's events"},"metadata":{"type":"object","note":"up to 20 string key/value pairs"},"coins":{"type":"array","items":["USDT_ETH","USDT_SOL","USDT_BSC","USDC_SOL","USDC_BSC","BTC","LTC","DOGE","ETH","BNB","SOL","TRX","XMR"],"note":"limit choice; default = all enabled coins (coins without a payout wallet collect in the merchant balance)"},"coin":{"type":"string","enum":["USDT_ETH","USDT_SOL","USDT_BSC","USDC_SOL","USDC_BSC","BTC","LTC","DOGE","ETH","BNB","SOL","TRX","XMR"],"note":"lock one coin; response then includes address + crypto_amount"},"expires_in":{"type":"integer","unit":"seconds","default":3600,"min":300,"max":604800}},"returns":"payment (201)"},{"method":"GET","path":"/payments/{id}","summary":"Retrieve a payment","returns":"payment"},{"method":"GET","path":"/payments","summary":"List payments, newest first","query":{"limit":"1-100, default 10","starting_after":"payment id for the next page","status":"filter by status"},"returns":"{ object: 'list', data: payment[], has_more: boolean }"},{"method":"POST","path":"/payments/{id}/extend","summary":"Keep an open payment alive longer or reopen an expired unpaid one","params":{"seconds":{"type":"integer","default":3600}},"returns":"payment"},{"method":"POST","path":"/payments/{id}/cancel","summary":"Cancel while nothing was paid","returns":"payment"},{"method":"POST","path":"/payments/{id}/simulate","summary":"Sandbox only (sk_test_ key): finish a test payment and send its webhook","params":{"outcome":{"type":"string","enum":["paid","underpaid","expired"],"default":"paid"}},"returns":"payment"}],"objects":{"payment":{"id":"string, format NXT-YYYYMMDD-#########-<account uuid>-#########","object":"'payment'","livemode":"boolean","status":"awaiting_coin | awaiting_payment | confirming | paid | underpaid | expired | canceled","amount":"string (fiat)","currency":"USD | EUR","description":"string|null","brand":"string|null","order_id":"string|null","metadata":"object","items":"{ name, quantity, amount|null, image_url|null }[]","coins":"string[] offered","coin":"string|null chosen coin","network":"string|null","address":"string|null one-time deposit address","crypto_amount":"string|null exact amount to send","amount_received":"string|null","tx_hash":"string|null","confirmations":"integer","fee_percent":"string|null","url":"string hosted payment page","success_url":"string|null","cancel_url":"string|null","webhook_url":"string|null","created":"unix seconds","expires_at":"unix seconds","paid_at":"unix seconds|null","canceled_at":"unix seconds|null"},"error":{"error":{"type":"invalid_request_error | authentication_error | permission_error | rate_limit_error | api_error","code":"string","message":"string","param":"string (optional)"}}},"statuses":{"awaiting_coin":"created, customer hasn't picked a coin","awaiting_payment":"address issued, waiting for the transaction","confirming":"transaction seen, waiting for confirmations","paid":"confirmed, safe to fulfil","underpaid":"less than the full amount arrived","expired":"nothing arrived in time (1 hour unless extended)","canceled":"canceled by the merchant"},"errors":{"400":"invalid parameter (see param)","401":"missing or invalid key","403":"account suspended (message has reason and end date)","404":"no such payment","409":"payment not in a state that allows this","429":"rate limited","500":"server error, retry with the same Idempotency-Key"},"webhooks":{"method":"POST","content_type":"application/json","events":{"payment.paid":"fulfil the order","payment.underpaid":"only part arrived before the window closed; amount_received has the amount (it is settled to the merchant). The customer can still send the rest to the same address, then payment.paid follows; until then do not fulfil","payment.expired":"release the order","payment.canceled":"release the order","test":"sent from the dashboard"},"event_shape":{"id":"evt_...","object":"event","type":"payment.paid","created":"unix seconds","data":{"object":"payment"}},"retries":"30s, 2m, 10m, 30m, 1h, 2h, 4h, 8h until a 2xx response","signature":{"header":"NxtPay-Signature","format":"t=<unix seconds>,v1=<hex hmac>","algorithm":"HMAC-SHA256 with the webhook signing secret over the string `${t}.${raw_body}`, hex encoded","checks":["compare v1 in constant time","reject if |now - t| > 300 seconds"],"example_node":"const p=Object.fromEntries(header.split(',').map(x=>x.split('=')));const mac=crypto.createHmac('sha256',secret).update(p.t+'.'+rawBody).digest('hex');const ok=Math.abs(Date.now()/1000-Number(p.t))<=300&&mac.length===p.v1.length&&crypto.timingSafeEqual(Buffer.from(mac),Buffer.from(p.v1));","example_php":"parse_str(str_replace(',', '&', $header), $p); $ok = abs(time() - (int)$p['t']) <= 300 && hash_equals(hash_hmac('sha256', $p['t'].'.'.$raw, $secret), $p['v1'] ?? '');","example_python":"p=dict(x.split('=',1) for x in header.split(','));ok=abs(time.time()-int(p['t']))<=300 and hmac.compare_digest(hmac.new(secret.encode(),p['t'].encode()+b'.'+raw,hashlib.sha256).hexdigest(),p.get('v1',''))"}},"checkout":{"hosted_page":"payment.url on https://pay.nxtpay.wtf","embed":{"script":"https://pay.nxtpay.wtf/embed.js","usage":"<button data-nxtpay=\"{payment.url}\">Pay with crypto</button>","js_api":"window.NxtPay.open(payment.url)"},"redirect":"after confirmation the page shows a receipt and redirects to success_url after 5 seconds"},"coins":[{"code":"USDT_ETH","name":"Tether","network":"Ethereum","confirmations":12},{"code":"USDT_SOL","name":"Tether","network":"Solana","confirmations":"finalized"},{"code":"USDT_BSC","name":"Tether","network":"BNB Chain","confirmations":15},{"code":"USDC_SOL","name":"USD Coin","network":"Solana","confirmations":"finalized"},{"code":"USDC_BSC","name":"USD Coin","network":"BNB Chain","confirmations":15},{"code":"BTC","name":"Bitcoin","network":"Bitcoin","confirmations":2},{"code":"LTC","name":"Litecoin","network":"Litecoin","confirmations":3},{"code":"DOGE","name":"Dogecoin","network":"Dogecoin","confirmations":6},{"code":"ETH","name":"Ethereum","network":"Ethereum","confirmations":12},{"code":"BNB","name":"BNB","network":"BNB Chain","confirmations":15},{"code":"SOL","name":"Solana","network":"Solana","confirmations":"finalized"},{"code":"TRX","name":"Tron","network":"Tron","confirmations":20},{"code":"XMR","name":"Monero","network":"Monero","confirmations":10}],"fees":{"start":"2%","after_10k_total_sales":"1.5%","months_with_50k_plus_sales":"1%","note":"taken from each payment; network fees for forwarding come out of the forwarded amount"},"example_create":{"curl":"curl https://api.nxtpay.wtf/v1/payments -H \"Authorization: Bearer $NXTPAY_KEY\" -H \"Idempotency-Key: order_8812\" -d amount=49.99 -d currency=USD -d order_id=8812 -d success_url=https://shop.example/thanks -d \"metadata[user_id]=42\""}}