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_KEY

Base URL

https://api.nanswap.com/pay

POST /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
}

Always verify the webhook signature x-nanswap-sig when processing webhooks
Verify that the priceAmount and priceCurrency in the payload match your expected values.
Make sure your callback is idempotent: the same webhook may be sent multiple times.
If you are using "Dynamic Address" in your Nanswap Pay Settings, also check that the payoutAddress in the payload match the expected values.

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]