Testing In Sandbox | Bitnob API Reference

Testing Lightning in sandbox

Sandbox simulates the Lightning Network. Create invoices, receive payments and send payments with the same API calls you use in live, and get the same balance changes and webhooks. No real bitcoin moves.

How it works

Sandbox invoices are real, signed testnet BOLT11 invoices (they start with lntb). They decode in any Lightning library and work in QR codes.

Nothing pays a sandbox invoice on its own. You trigger the payment in one of three ways, below.

When an invoice is paid, your sandbox balance is credited and you receive the usual payment webhook, usually within 2 seconds.

Receive a payment

Create an invoice, then pay it using any of these:

Simulate a payment. Call the simulate endpoint on one of your open invoices.

Auto-settle. Create the invoice with "auto_settle": true and it is paid about 5 seconds later.

Pay it from another sandbox account. A second sandbox business pays your lntb invoice with the normal pay endpoint.

Create an invoicePOST/api/lightning/invoices
Simulate a paymentPOST/api/lightning/invoices/:invoice_id/simulate-payment
Send a paymentPOST/api/lightning/pay

Try It Out

Create an invoice

Use Case

Create the invoice with "auto_settle": true and it is paid about 5 seconds later.

Sandbox only

auto_settle is rejected in live.

Endpoint

Request Body

amountnumberRequired

The invoice amount in satoshis.

descriptionstringRequired

What the payment is for. Shown in the payer's wallet.

referencestringRequired

A unique idempotency key for this request.

auto_settlebooleanOptional

Sandbox only. Set to true and the invoice is paid about 5 seconds after it is created. Rejected in live.

Example Request

Response Body (201)

idstringRequired

The invoice ID. Use it to retrieve the invoice or simulate a payment.

payment_hashstringRequired

Hash that identifies this payment on the Lightning Network.

requeststringRequired

The testnet BOLT11 invoice string. Starts with lntb.

amount_satstringRequired

The invoice amount in satoshis.

descriptionstringRequired

The description attached to the invoice.

statusstringRequired

pending when created. Moves to paid about 5 seconds later.

expires_atstringRequired

ISO 8601 timestamp when the invoice expires.

created_atstringRequired

ISO 8601 timestamp when the invoice was created.

Example Response (201)

Try It Out

Simulate a payment

Use Case

The invoice must belong to your business, be unpaid and not expired. An invoice that is already paid or expired returns a 4xx error.

Endpoint

Response Body (200)

successBooleanRequired

Whether the simulated payment was accepted.

messageStringRequired

Human-readable status message describing the result.

data.invoice_idUUIDRequired

The ID of the invoice being paid.

data.payment_hashStringRequired

The payment hash of the invoice being paid.

Example Response (200)

Try It Out

Send a payment

Use Case

Pay any lntb invoice with the normal pay endpoint.

Endpoint

Request Body

requeststringRequired

The lntb invoice to pay.

referencestringRequired

A unique idempotency key for this request.

Example Request

Good to know

Sandbox can only pay testnet (lntb) invoices. Paying a mainnet lnbc invoice returns an error.

The normal balance check still applies: paying more than your sandbox balance returns an insufficient-balance error.

Each invoice can be paid once. A second payment returns "invoice is already paid".

Expired invoices cannot be paid or simulated.

Lightning addresses work the same way: invoices they create can be settled with any of the three methods.

Dashboard users can call POST /dashboard/lightning/invoices/{id}/simulate-payment.