# Invoices

The following request uses illustrative order values. Response IDs, addresses, rates and timestamps below are examples, not current market rates or reusable payment destinations.

```bash
curl -X POST https://api.satlane.com/v1/invoices \
  -H "SatLane-Version: 2026-10-05" \
  -H "Authorization: Bearer sl_test_XXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123-attempt-1" \
  -d '{
    "amount": 49.99,
    "currency": "USD",
    "order_ref": "ORD-12345",
    "success_url": "https://yourshop.com/orders/ORD-12345/thanks",
    "buyer_email": "buyer@example.com",
    "expires_in_minutes": 15,
    "metadata": { "cart_id": "abc123" }
  }'
```

This creation example targets an installation with wallet-free Sandbox enabled. Use your deployment origin and confirmed contract for another installation. A webhook endpoint is optional for manual checkout; configure one for the matching environment before testing automated fulfillment.

Always send an `Idempotency-Key` on API creation. Successful responses are retained for 24-hour replay. Enabled creation stores the invoice and idempotency result atomically under a scoped reservation; reuse the same key and body after an uncertain result. A conflicting body is rejected. Legacy installations only provide the older response-cache behavior, so use sequential retries. Neither API replay nor invoice creation removes the need for order-level reconciliation and webhook deduplication. The session-authenticated dashboard form does not expose this API-key idempotency contract.

## Request fields

| Field                | Type   | Required | Notes                                                                                                                                |
| -------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `amount`             | number | one of   | Fiat amount. We lock a BTC/USD rate and convert to sats.                                                                             |
| `currency`           | string | one of   | Must be `"USD"` today.                                                                                                               |
| `amount_sats`        | string | one of   | Skip fiat conversion; charge exact sats (digits only).                                                                               |
| `order_ref`          | string | optional | Your internal order ID. Max 255 chars.                                                                                               |
| `callback_url`       | string | optional | Stored invoice metadata. Current delivery uses registered store webhook endpoints; this field does not override them.                |
| `success_url`        | string | optional | Hosted checkout redirects here after payment.                                                                                        |
| `buyer_email`        | string | optional | Buyer email for receipts / support.                                                                                                  |
| `expires_in_minutes` | int    | optional | 5–120. Public API default is the configured platform expiry (15 minutes by default). The dashboard store form uses the store expiry. |
| `metadata`           | object | optional | Free-form `string → string` map (values max 255 chars). Echoed on webhooks.                                                          |

Provide either `(amount + currency)` **or** `amount_sats`, not both.

## Response

Illustrative enabled Sandbox response. Nullable destinations must stay null in your models and UI. Live responses contain a mainnet destination; legacy responses may contain a Test destination.

```json
{
  "invoice": {
    "id": "22872e14-4216-4c78-8fe1-088ea649f3c2",
    "store_id": "…",
    "vendor_id": "…",
    "status": "pending",
    "environment": "test",
    "address": null,
    "payment_destination": {
      "kind": "simulated",
      "network": null,
      "address": null,
      "payment_uri": null
    },
    "amount_sats": "150234",
    "amount_btc": "0.00150234",
    "amount_fiat": 49.99,
    "fiat_currency": "USD",
    "btc_usd_rate": 33280.45,
    "rate_locked_at": "2026-05-16T11:15:00.000Z",
    "amount_tolerance_sats": "375",
    "amount_paid_sats": "0",
    "expires_at": "2026-05-16T11:30:00.000Z",
    "late_payment_grace_minutes": 60,
    "late_payment_deadline_at": "2026-05-16T12:30:00.000Z",
    "conf_threshold": 1,
    "fee_sats": "0",
    "payment_uri": null,
    "hosted_checkout_url": "https://pay.satlane.com/i/22872e14-4216-4c78-8fe1-088ea649f3c2",
    "payment_phase": "awaiting_payment",
    "order_ref": "ORD-12345",
    "created_at": "2026-05-16T11:15:00.000Z",
    "paid_at": null
  }
}
```

## Response fields worth understanding

| Field                      | What it means                                                                                                                                                                                                                        |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `amount_sats`              | Invoice amount in satoshis. Vendor-facing source of truth.                                                                                                                                                                           |
| `amount_paid_sats`         | Running total of sats received on-chain so far (non-reverted). Remaining = `amount_sats - amount_paid_sats`.                                                                                                                         |
| `amount_tolerance_sats`    | Slack on the expected amount. Payments within `[amount_sats − tolerance, amount_sats + tolerance]` count as exact. Defaults come from platform setting `payment_tolerance_bp` (default 25 bp = 0.25%), clamped to `[10, 1000]` sats. |
| `btc_usd_rate`             | BTC/USD rate locked at creation. Later price moves do not change what the buyer owes.                                                                                                                                                |
| `late_payment_deadline_at` | ISO timestamp past which payments are no longer auto-credited. Active monitoring runs through that deadline; recovery monitoring may follow.                                                                                         |
| `conf_threshold`           | Confirmations required before status flips to `paid`. Defaults: 1 below $100 invoice value, 2 at $100+.                                                                                                                              |
| `fee_sats`                 | Platform take-rate on this invoice, accrued to your vendor account when a **live** invoice is paid. Visible in dashboard billing.                                                                                                    |
| `payment_phase`            | Buyer-facing lifecycle dimension computed at read time. Values include `awaiting_payment`, `payment_detected`, `confirming`, `settled`, `shortfall`, `excess`, `needs_review`, `grace_period`, `recovery_window`, and `closed`.      |
| `payment_summary`          | Expected, received and remaining sats, latest-payment confirmations, latest transaction ID and grace deadline. Received totals are not confirmed coverage. Treat sats values as strings.                                                                                                            |
| `checkout_urls`            | Optional checkout URL alternatives. Prefer `hosted_checkout_url` for the standard hosted flow; do not assume alternatives are always present.                                                                                        |
| `hosted_checkout_url`      | Ready-to-redirect hosted payment page.                                                                                                                                                                                               |

---