Payments

Create a payment

POST/api/v2/payments

Ask the merchant's own wallet for a Lightning invoice and register the sale. Returns a bolt11 the customer pays directly to that wallet — Trevi is never a hop. This is the one call a storefront integration needs.

Returns 200 with { success: true, payment: {…} }. The invoice field is a bolt11 issued by the merchant's wallet, valid for 15 minutes.
Idempotent on (merchant, external_order_id). Re-sending the same external_order_id returns the ORIGINAL payment — including its original invoice and amount — rather than creating a second invoice for one sale. Retry freely after a timeout; use a new order id for a genuinely new sale.
400 — amount_sats is missing, not a whole number, or below 1; or external_order_id is missing or empty.
409 with code: "no_connection" — this merchant has not connected a wallet yet. There is no invoice to issue because there is no wallet to issue it.
502 with a code naming the failure kind — the merchant's wallet refused or could not be reached. No money moved; retry or fall back to another payment method.
Cashback needs no separate call. Supply customer_lightning_address for an instant payout, or customer_email for a claim link; supply neither and no cashback is offered.

Authentication

Accepts either an API key (X-API-Key) or a dashboard JWT (Authorization: Bearer …).

Body parameters

amount_satsnumber (integer)required

whole satoshis, minimum 1. No fiat conversion — convert on your side.

external_order_idstringrequired

your own order reference. Makes this call idempotent.

descriptionstringoptional

goes into the invoice description

webhook_urlstringoptional

receives the order.confirmed callback when the sale settles

customer_lightning_addressstringoptional

enables INSTANT cashback to this address

customer_emailstringoptional

used only when no Lightning address is known — Trevi emails a 30-day claim link

POST/api/v2/payments

curl --request POST "https://api.trevi.cash/api/v2/payments" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $TREVI_API_KEY" \
  --data '{
    "amount_sats": 150000,
    "external_order_id": "order-12345",
    "description": "Order #12345",
    "webhook_url": "https://yoursite.com/webhooks/trevi",
    "customer_lightning_address": "alice@getalby.com"
  }'

200Sample response

{
  "success": true,
  "payment": {
    "payment_id": "pay_abc123def456abc123def456abc123de",
    "external_order_id": "order-12345",
    "amount_sats": 150000,
    "invoice": "lnbc1500u1p…",
    "payment_hash": "9f2c8e1a…",
    "status": "pending",
    "expires_at": "2026-08-13T12:15:00.000Z"
  }
}

Was this page helpful?

Health check

Read a payment