3. Invoices REST API
Generated
Invoice created via API
Pending
Awaiting customer payment
Paid
Transaction detected in mempool (0-conf) or LN
Settled
Confirmed on-chain block
POST/api/v1/invoices
Generate a dynamic invoice. Returns pricing metadata, converted satoshi values, derived Segwit addresses, and LND payment hashes.
orderId(String, optional) — External transaction reference.total(Number, required) — Price of purchase in fiat or satoshis.items(Array, optional) — Breakdown of SKU items (name, quantity, price).isEscrow(Boolean, optional) — Set totrueto generate a 2-of-3 Multisig P2WSH Trustless Escrow address.escrowBuyerPubkey(String, required if isEscrow) — Buyer's 33-byte hex Bitcoin public key for the multisig contract.
// JSON RESPONSE:
{
"id": "inv_550e8400-e29b-41d4-a716-446655440000",
"orderId": "ord-12345",
"total": 100.00,
"platformFee": 0.00,
"merchantSettlement": 100.00,
"btcAmount": 0.00153846,
"bitcoinAddress": "bc1q8t58g2fsww45656ghnqyqwer79yhqwer987654",
"lightningInvoice": "lnbc1538460n1p0...",
"isEscrow": false,
"status": "pending",
"expiresAt": "2026-05-23T18:15:30.000Z"
}GET/api/v1/invoices/:id
Retrieve checkout metadata and status values for a dynamic invoice. Unauthenticated request allowed to serve public hosted checkout. Rate Limited: To prevent scraping, this endpoint is strictly limited to 10 requests per minute per IP. If you are polling for status updates, please handle 429 Too Many Requests responses gracefully and respect the X-RateLimit-Reset header.
async function pollInvoice(invoiceId) {
try {
const res = await fetch(`/api/v1/invoices/${invoiceId}`);
// Handle Rate Limiting (429)
if (res.status === 429) {
const resetTime = new Date(res.headers.get('X-RateLimit-Reset')).getTime();
const waitTime = Math.max(resetTime - Date.now(), 5000);
console.warn(`Rate limited. Waiting ${waitTime}ms before retrying...`);
// Wait until the reset window before polling again
await new Promise(resolve => setTimeout(resolve, waitTime));
return pollInvoice(invoiceId);
}
const data = await res.json();
if (data.status === 'paid' || data.status === 'confirmed') {
window.location.href = '/success';
} else if (data.status === 'expired') {
alert('Invoice expired!');
} else {
// Continue polling every 10 seconds (staying under the 10/min limit)
setTimeout(() => pollInvoice(invoiceId), 10000);
}
} catch (err) {
console.error("Polling error:", err);
}
}POST/api/v1/invoices/:id/cancel
Transition an active invoice state to canceled. Allowed if invoice status is currently pending.
POST/api/escrow/spend
Submit a signed PSBT to release or refund funds locked in a 2-of-3 Multisig Trustless Escrow contract. The platform will co-sign and broadcast the transaction.
invoiceId(String, required) — The ID of the Escrow invoice.action(String, required) — Either"release"or"refund".psbt(String, required) — The partially signed Bitcoin transaction (Base64 or Hex) containing the buyer's or seller's signature.