REST API
Create invoices and receive webhooks programmatically. Requires a secret API key from your Nanswap Pay dashboard.
Authentication
Pass your secret API key in the
x-nanswap-pay-key request header for all authenticated endpoints.x-nanswap-pay-key: YOUR_SECRET_API_KEYBase URL
https://api.nanswap.com/payPOST /order
Create a new payment invoice. Returns a deposit address the customer should send funds to.
Request headers
| Parameter | Type | Required | Description |
|---|---|---|---|
x-nanswap-pay-key | string | required | Your secret API key. |
Request body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
priceAmount | number | required | Amount to charge, in priceCurrency. |
priceCurrency | string | optional | Currency of the price (e.g. USD, EUR, XNO). Defaults to your payout currency. Check /fiat-currencies for available options. |
payinCurrency | string | optional | Currency the customer pays in (e.g. XNO, BAN, BTC, ETH). Check /payin-currencies for available options. Do not specify it to let user pay with any cryptocurrency. |
invoiceId | string | optional | Your internal order ID (max 128 chars). Returned as invoiceIdPartner. |
callbackUrl | string | optional | Webhook URL to notify on status changes. |
successUrl | string | optional | URL to redirect the customer after a successful payment. |
cancelUrl | string | optional | URL to redirect the customer after cancellation. |
payoutAddress | string | optional | Override payout address (only valid when your payout method is set to "dynamic"). |
payoutCurrency | string | optional | Override payout currency (XNO, NANUSD, USDT-MATIC). Defaults to your dashboard setting. |
Example request
curl -X POST https://api.nanswap.com/pay/order \
-H "Content-Type: application/json" \
-H "x-nanswap-pay-key: YOUR_SECRET_API_KEY" \
-d '{
"priceAmount": 10,
"priceCurrency": "USD",
"payinCurrency": "XNO",
"invoiceId": "order_123",
"callbackUrl": "https://example.com/webhooks/nanswap",
"successUrl": "https://example.com/thank-you",
"cancelUrl": "https://example.com/cart"
}'Example response
{
"success": true,
"invoiceId": "abc123...",
"invoiceIdPartner": "order_123",
"payinCurrency": "XNO",
"paymentCurrency": "NANUSD",
"payinAddress": "nano_1abc...",
"expectedAmountFrom": 12.345,
"expectedPayoutAmount": "10.000",
"expireAt": "2024-01-01T00:05:00.000Z",
"status": "waiting",
"paymentLink": "https://nanswap.com/pay/abc123..."
}GET /order
Get the current status of an invoice by its transaction ID. No authentication required.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | required | The invoiceId returned when the order was created. |
Example request
curl "https://api.nanswap.com/pay/order?id=abc123"Example response
{
"status": "completed",
"invoiceId": "abc123...",
"invoiceIdPartner": "order_123",
"payinCurrency": "XNO",
"paymentCurrency": "NANUSD",
"expectedAmountFrom": 12.345,
"expectedPayoutAmount": 10,
"expireAt": "2024-01-01T00:05:00.000Z",
"depositDetectedAt": "2024-01-01T00:01:30.000Z",
"completedAt": "2024-01-01T00:02:00.000Z",
"successUrl": "https://example.com/thank-you",
"cancelUrl": "https://example.com/cart"
}Order statuses
| Status | Description |
|---|---|
pending-currency | Awaiting customer to select a currency to pay with. |
waiting | Awaiting customer payment. |
processing | Payment received, payout is being sent. |
completed | Payout sent successfully. |
underpaid | Customer paid less than the required amount. |
error | An error occurred (e.g. price moved too much, payout failed). |
processing-error | Payment received but payout sending failed. Contact support. |
GET /order-estimate
Get an estimated amount the customer needs to pay before creating an invoice. Useful for showing a price preview. Accepts your secret API key or public key.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
payinCurrency | string | required | Currency the customer pays in (e.g. XNO, BTC). |
priceAmount | number | required | Amount to charge, in priceCurrency. |
priceCurrency | string | optional | Currency of the price (e.g. USD, EUR). Defaults to payout currency. |
payoutCurrency | string | optional | Override payout currency. Defaults to your dashboard setting. |
Example request
curl "https://api.nanswap.com/pay/order-estimate?payinCurrency=XNO&priceAmount=10&priceCurrency=USD" \
-H "x-nanswap-pay-key: YOUR_SECRET_API_KEY"Example response
{
"expectedAmountFrom": 12.345,
"payoutAmount": 10.00,
"payoutCurrency": "NANUSD",
"warningHighFees": false
}GET /invoices
List all invoices for your merchant account, sorted by most recent. Paginated at 20 per page.
Request headers
| Parameter | Type | Required | Description |
|---|---|---|---|
x-nanswap-pay-key | string | required | Your secret API key. |
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | number | optional | Page number (default: 1). |
Example request
curl "https://api.nanswap.com/pay/invoices?page=1" \
-H "x-nanswap-pay-key: YOUR_SECRET_API_KEY"Example response
{
"invoices": [
{
"invoiceId": "abc123...",
"invoicePartnerId": "order_123",
"status": "completed",
"payinCurrency": "XNO",
"payoutCurrency": "NANUSD",
"expectedAmountFrom": 12.345,
"expectedPayoutAmount": 10,
"payoutAmount": 10,
"payoutHash": "hash...",
"createdAt": "2024-01-01T00:00:00.000Z"
}
],
"total": 42,
"page": 1,
"pages": 3
}GET /payin-currencies
Returns all currencies available for the customer to pay in (the
payinCurrency field). No authentication required.Example request
curl "https://api.nanswap.com/pay/payin-currencies"Example response
{
"XNO": { "name": "Nano", "ticker": "XNO", ... },
"BAN": { "name": "Banano", "ticker": "BAN", ... },
"BTC": { "name": "Bitcoin", "ticker": "BTC", ... },
...
}GET /fiat-currencies
Returns all currencies available as
priceCurrency when creating an order or fetching an estimate. Includes fiat currencies (USD, EUR, GBP, …) and XNO. No authentication required.Example request
curl "https://api.nanswap.com/pay/fiat-currencies"Example response
["USD", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "XNO", ...]Webhooks
When a
callbackUrl is set on an order, Nanswap Pay sends a POST request to that URL each time the invoice status changes.Payload
{
"invoicePartnerId": "order_123",
"invoiceId": "abc123...",
"status": "completed",
"expectedAmountFrom": 12.345,
"amountFrom": 12.345,
"payoutAmount": 10,
"payoutCurrency": "NANUSD",
"payinCurrency": "XNO",
"priceCurrency": "USD",
"priceAmount": 10,
"payoutMethod": "address", // "address", "internal" or "dynamic"
"payoutHash": "hash...", // if payoutAddress was set
"payoutAddress": "nano_1abc..." // if payoutAddress was set
}Signature verification
Webhook request includes an
x-nanswap-sig header. Verify it by computing HMAC-SHA512 of the JSON payload with keys sorted alphabetically, using your webhook secret.// Node.js example
const crypto = require('crypto')
function verifySignature(payload, secret, signature) {
const sorted = JSON.stringify(payload, Object.keys(payload).sort())
const expected = crypto
.createHmac('sha512', secret)
.update(sorted)
.digest('hex')
return expected === signature
}
// In your webhook handler:
const isValid = verifySignature(req.body, WEBHOOK_SECRET, req.headers['x-nanswap-sig'])
// Only if using payoutAddress overrides, also check that the payoutAddress in the payload match the expected values for the order to prevent tampering.
if (payload.payoutAddress !== expectedPayoutAddress) {
// Handle potential tampering
}
Need help with the integration? Contact us at [email protected]

