POST
/api/v1/invoices≡ NowPayments POST /v1/invoiceCreate an invoice
Creates a payment invoice for the requested amount on the requested chain. Nowpay generates an HD-derived deposit address (BIP44 m/44'/60'/0'/0/<index>), queues an invoice.waiting webhook, and returns the hosted checkout URL your customer can be redirected to. The deposit address is unique per invoice — never reused. For network="bitcoin", the response includes bolt11, payment_hash, amount_sats, amount_btc, and btc_usd_rate instead of an EVM address; the customer pays by scanning the QR code with their Bitcoin wallet using the locked exchange rate at creation time. For network="pix", the response includes a Pix charge (pix_code + pix_qr_code + amount_brl); the customer pays a Pix charge in BRL and the merchant receives USDT (powered by Hodle).
| Parameter | Type | Required | Description |
|---|---|---|---|
| amount | string | yes | USDT amount (e.g. "50.00"). Numeric string — never a JS number. |
| network | string | yes | One of: bsc, polygon, arbitrum, optimism, base, bitcoin, pix. pix. |
| delivery_network | string | no | (Pix only) EVM chain where USDT will be delivered (bsc, polygon, arbitrum, optimism, base). Defaults to merchant's first enabled chain. |
| external_id | string | no | Merchant-internal order ID for reconciliation. |
| success_url | string | no | Redirect URL after successful payment. |
| cancel_url | string | no | Redirect URL after cancellation/timeout. |
| metadata | object | no | Arbitrary JSON metadata stored with the invoice. |
Request example
request.sh
# EVM invoice (polygon)
curl -X POST https://nowpay.finance/api/v1/invoices \
-H "x-api-key: sk_live_4f3c2b1a9e8d7c6b5a4f3e2d1c0b9a8f" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 9b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e" \
-d '{
"amount": "50.00",
"network": "polygon",
"external_id": "order_12345",
"success_url": "https://shop.example.com/thanks",
"cancel_url": "https://shop.example.com/cart"
}'
# BTC invoice (bitcoin)
curl -X POST https://nowpay.finance/api/v1/invoices \
-H "x-api-key: sk_live_4f3c2b1a9e8d7c6b5a4f3e2d1c0b9a8f" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 9b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e" \
-d '{
"amount": "100.00",
"network": "bitcoin",
"external_id": "order_btc_123"
}'
# Pix invoice (customer pays BRL via Pix, merchant receives USDT)
curl -X POST https://nowpay.finance/api/v1/invoices \
-H "x-api-key: sk_live_4f3c2b1a9e8d7c6b5a4f3e2d1c0b9a8f" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 9b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e" \
-d '{
"amount": "100.00",
"network": "pix",
"delivery_network": "polygon",
"external_id": "order_pix_456"
}'Response example
response.json
// EVM (polygon) invoice
{
"id": "inv_abc123",
"status": "waiting",
"address": "0x7d5a3f9c2b1e8a4d6f0c2b5a7e9d1f3c4b2a8e6d",
"amount": "50.00",
"network": "polygon",
"expires_at": "2026-01-01T12:00:00.000Z",
"checkout_url": "https://nowpay.finance/i/inv_abc123"
}
// BTC (bitcoin) invoice
{
"id": "inv_btc456",
"status": "waiting",
"network": "bitcoin",
"amount": "100.00",
"amount_sats": "166667",
"amount_btc": "0.00166667",
"btc_usd_rate": 60000,
"bolt11": "lnbc1666670n1pj3...",
"payment_hash": "a1b2c3d4e5f6...",
"expires_at": "2026-01-01T13:00:00.000Z",
"checkout_url": "https://nowpay.finance/i/inv_btc456"
}
// Pix (customer pays BRL, merchant receives USDT)
{
"id": "inv_pix789",
"status": "waiting",
"network": "pix",
"amount": "100.00",
"amount_brl": "558.25",
"pix_code": "00020126360014BR.GOV.BCB.PIX0114...",
"pix_qr_code": "data:image/png;base64,iVBORw0KG...",
"pix_expires_at": "2026-01-01T14:00:00.000Z",
"delivery_network": "polygon",
"expires_at": "2026-01-01T14:00:00.000Z",
"checkout_url": "https://nowpay.finance/i/inv_pix789"
}Error codes
| Code | Status | Description |
|---|---|---|
| invalid_amount | 400 | amount missing or not a positive numeric string. |
| invalid_network | 400 | network is not a supported chain code. |
| network_inactive | 400 | chain exists in config but is not active. |
| idempotency_conflict | 409 | Idempotency-Key reused with a different body. |