Guides

Quickstart: a sale, end to end

Connect your wallet, create a payment, show the invoice, and let Trevi handle order confirmation and cashback. Four steps, one API call from your server.

Step 1 — connect your wallet, once. In the Trevi dashboard, connect an NWC-compatible wallet and approve a daily spending limit. Cashback cannot be enabled until a wallet is connected: Trevi refuses to promise a payout it has not verified your wallet can cover.

Step 2 — create an API key in the dashboard and keep it server-side. Never call the Trevi API from a browser; the key authenticates as your whole merchant account.

Step 3 — at checkout, POST the sale to /api/v2/payments with amount_sats and your own external_order_id. You get back a bolt11 invoice issued by your own wallet. Render it as a QR code. The customer pays your wallet directly.

Step 4 — learn that it settled. Either pass a webhook_url and receive an order.confirmed callback, or poll GET /api/v2/payments/:paymentId until status is paid. Webhooks are strongly preferred.

Cashback is automatic and needs no extra call: pass customer_lightning_address for an instant payout, or customer_email to have Trevi email the customer a claim link. Pass neither and no cashback is offered.

The call is idempotent on (merchant, external_order_id). If your request times out, send exactly the same body again — you get the original payment back, never a second invoice for the same order. This is what stops a customer being able to pay twice.