Invoice API
The Invoice API allows you to create and manage payment invoices for Nano cryptocurrency.
Endpoints
Create an Invoice
Creates a new invoice for payment processing.
Endpoint: POST /api/v1/invoices
Authentication: API Key (optional for free tier)
Request Body:
JSON
1 { 2 "nominal_amount": 29.9, 3 "nominal_currency": "EUR", 4 "destinations": [ 5 { 6 "account": "nano_123...", 7 "primary": true 8 }, 9 { 10 "account": "nano_27g9ge50ri4", 11 "nominal_amount": 10, 12 "description": "Fixed amount in nominal currency" 13 }, 14 { 15 "account": "nano_3v7vtpj1exd", 16 "percentage": 10, 17 "description": "Percentage based on invoice nominal_amount" 18 } 19 ] 20 }
Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| nominal_amount | decimal | Yes | The amount in the specified fiat currency |
| nominal_currency | string | Yes | The fiat currency code (e.g., USD, EUR) |
| destinations | array | Yes* | Payment destinations (required if forward_account not provided). Defines where the received Nano should go. |
| forward_account | string | Yes* | Forward address (required if destinations not provided). If used, received Nano is sent entirely to this single address. |
| webhook_url | string | No | URL to receive payment status notifications |
| webhook_secret | string | No | Secret used for verifying webhook signature |
| user_data | string | No | Custom data to associate with the invoice (will be included in webhooks) |
| show_qr | boolean | No | Whether to include QR code data in the response (default: false) |
| reference | string | No | Your internal reference for the invoice (e.g., order ID) |
| simulate | boolean | No | If true, simulates the invoice creation (calculates amounts, fees) without actually creating a payable invoice. Useful for previewing. (default: false) |
Destination Object (in Request):
| Parameter | Type | Required | Description |
|---|---|---|---|
| account | string | Yes | The Nano address for this destination |
| primary | boolean | No | Marks this as the main destination. If true, its amount is calculated as total_nominal_amount - sum(other_destination_amounts) - service_fee. Only one primary destination allowed. Cannot be used with percentage or amount. |
| percentage | decimal | No | Percentage of the total nominal amount to send to this account. Cannot be used with primary or amount. |
| amount | decimal | No | Fixed nominal amount (in nominal_currency) to send to this account. Cannot be used with primary or percentage. |
| description | string | No | A description for this destination (e.g., "Platform Fee") |
Response (Create Invoice):
This is the structure returned when an invoice is successfully created or simulated.
JSON
1 { 2 "invoice_id": "INV_2025_03_d1447da3e9ff90cd3822", 3 "secret_id": "INV_SECRET_02122c244c4a33453dbc4", 4 "account_address": "nano_1payment_address", 5 "nominal_currency": "EUR", 6 "formatted_currency": "XNO", 7 "required": { 8 "unit_amount": "10020763000000000000000000000000", 9 "formatted_amount": "10.020763", 10 "nominal_amount": "10" 11 }, 12 "received": { 13 "unit_amount": "0", 14 "formatted_amount": "0", 15 "nominal_amount": "0" 16 }, 17 "exchange_rate": "0.997928", 18 "expires_at": "2025-03-25T20:24:03.090148Z", 19 "destinations": [ 20 { 21 "type": "primary", 22 "account": "nano_123...", 23 "unit_amount": "9970659185000000000000000000000", 24 "formatted_amount": "9.970659185", 25 "nominal_amount": "9.950" 26 }, 27 { 28 "type": "service_fee", 29 "account": "nano_1nowapi9w5hx3d4wb9swa88p8dd7tsf8xsycob3owy855sai6j9zuyztjzdj", 30 "unit_amount": "50103815000000000000000000000", 31 "formatted_amount": "0.050103815", 32 "nominal_amount": "0.050", 33 "description": "Service fee" 34 } 35 ], 36 "service_fee_rate": "0.50", 37 "show_qr": false, 38 "is_simulation": false, 39 "is_pending": false, 40 "is_paid": false, 41 "is_forwarded": false, 42 "is_done": false, 43 "is_expired": false, 44 "is_overpaid": false, 45 "uri_rfc_8905": "payto:nano/nano_1payment_address?amount=10020763000000000000000000000000", 46 "uri_nano": "nano:nano_1payment_address?amount=10020763000000000000000000000000" 47 }
Response Parameters:
| Parameter | Type | Description |
|---|---|---|
| invoice_id | string | Unique public identifier for the invoice. |
| secret_id | string | Unique secret identifier for the invoice (used for retrieval if invoice_id is lost, treat securely). |
| account_address | string | The Nano address where the payment must be sent. |
| nominal_currency | string | The fiat currency code used for the invoice (e.g., EUR, USD). |
| formatted_currency | string | The cryptocurrency used for payment (e.g., XNO for Nano). |
| required | object | Details about the amount required for payment. |
| required.unit_amount | string | The exact amount required in the smallest unit of the cryptocurrency (raw). |
| required.formatted_amount | string | The exact amount required, formatted as a decimal string (e.g., "10.020763"). |
| required.nominal_amount | string | The original requested nominal amount in nominal_currency. |
| received | object | Details about the amount received so far. |
| received.unit_amount | string | The amount received in the smallest unit of the cryptocurrency (raw). |
| received.formatted_amount | string | The amount received, formatted as a decimal string. |
| received.nominal_amount | string | The approximate nominal value of the received amount at the time of payment, in nominal_currency. |
| exchange_rate | string | The exchange rate used (1 nominal_currency = X formatted_currency). |
| expires_at | string | ISO 8601 timestamp indicating when the invoice expires. |
| destinations | array | An array detailing where the received funds will be distributed. Includes calculated service fees. |
| destinations[].type | string | The type of destination (e.g., primary, percentage, amount, service_fee). |
| destinations[].account | string | The Nano address for this destination. |
| destinations[].unit_amount | string | The amount allocated to this destination in the smallest unit (raw). |
| destinations[].formatted_amount | string | The amount allocated to this destination, formatted as a decimal string. |
| destinations[].nominal_amount | string | The approximate nominal value of the amount allocated to this destination in nominal_currency. |
| destinations[].description | string | Optional description for this destination. |
| service_fee_rate | string | The service fee percentage applied (e.g., "0.50" for 0.50%). |
| show_qr | boolean | Whether QR code data would be included (if requested and applicable). true/false. |
| is_simulation | boolean | Indicates if this was a simulation (true) or a real invoice (false). |
| is_pending | boolean | Indicates if the invoice has received partial payment (true) or not (false). |
| is_paid | boolean | Indicates if the required amount has been fully received (true) or not (false). |
| is_forwarded | boolean | Indicates if the received funds have been forwarded to the destination(s) (true) or not (false). |
| is_done | boolean | Indicates if the invoice lifecycle is complete (paid and forwarded/settled) (true) or not (false). |
| is_expired | boolean | Indicates if the invoice has expired without being fully paid (true) or not (false). |
| is_overpaid | boolean | Indicates if more than the required amount was received (true) or not (false). |
| uri_rfc_8905 | string | Payment URI according to RFC 8905 (payto: scheme). |
| uri_nano | string | Payment URI using the common nano: scheme. |
| (qr_code_url) | string | (Optional) If show_qr was true in the request, this field containing a URL to a QR code image might be present. |
Get Invoice by ID
Retrieves an invoice by its public ID.
Endpoint: GET /api/v1/invoices/{invoice_id}?show_qr={bool}
Authentication: None (public)
Path Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| invoice_id | string | Yes | The public invoice ID (e.g., INV_2025_...). |
Query Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| show_qr | boolean | No | Whether to include QR code data in response (default: false). |
Response: The response format is the same as the updated Response (Create Invoice) structure detailed above.
Get Invoice by Secret ID
Retrieves an invoice by its secret ID. Use this if you need to retrieve invoice details but only have the secret_id.
Endpoint: GET /api/v1/invoices/secret/{secret_id}?show_qr={bool}
Authentication: None (public, but the secret_id itself should be kept private)
Path Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| secret_id | string | Yes | The secret invoice ID (e.g., INV_SECRET_...). |
Query Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| show_qr | boolean | No | Whether to include QR code data in response (default: false). |
Response: The response format is the same as the updated Response (Create Invoice) structure detailed above.
Payment Flow
-
Create an Invoice: Use the POST /api/v1/invoices endpoint with your desired nominal amount, currency, and destination(s).
-
Display Payment Info: Show the user the account_address and the required Nano amount (required.formatted_amount or required.unit_amount). You can also use the provided URIs (uri_nano, uri_rfc_8905) or QR code (if show_qr=true) for easier payment.
-
Monitor Status: Check the invoice status periodically using GET /api/v1/invoices/{invoice_id} or listen for Webhook notifications. Look for changes in the received object and the boolean flags (is_pending, is_paid, is_done, is_expired).
-
Confirmation: Once is_paid becomes true, the payment is confirmed.
-
Settlement: The API service will then attempt to forward the funds to the specified destinations. Once successful, is_forwarded and is_done should become true.
Webhook Notifications
If you provide a webhook_url during invoice creation, your server will receive POST requests for significant events in the invoice lifecycle.
Events:
| Event | Description |
|---|---|
invoice.created | Invoice has been created |
invoice.paid | Payment has been received |
invoice.expired | Invoice has expired without payment |
invoice.forwarded | Funds have been forwarded (if using forward_account) |
invoice.done | Invoice processing is complete |
See Webhook Documentation for details