How ZapAPI works

ZapAPI is organized around a few core primitives. Understanding them up front makes every endpoint in the API Reference feel predictable.

The mental modelCopy Anchor Link

Account
 └── Project              (a website, app, or business)
      ├── API keys         (scoped to this project)
      ├── Settlement wallet (where this project's payments land)
      ├── Invoices         (one-time payments)
      ├── Payment links    (reusable checkout URLs)
      ├── Plans            (recurring billing tiers)
      ├── Subscriptions    (subscribers + renewals + dunning)
      ├── Refunds          (payment refunds + credit notes)
      ├── Webhook endpoints (event subscriptions)
      └── Customers        (CRM — auto-built from payments)

Accounts and projectsCopy Anchor Link

A ZapAPI account can own many projects. Almost every resource (invoices, payment links, webhooks, customers) is scoped to a project, and API keys are issued per-project. This lets you run a production store, a staging environment and a side project from a single account — with isolated keys, isolated webhooks, and isolated customers.

Wallets and settlementCopy Anchor Link

Every user gets an isolated LNbits sub-wallet. Funds are always attributable to a single user, withdrawal is always possible, and power users can connect their own node via NWC (NIP-47) instead of using the hosted wallet.

Each project has a settlement wallet — the destination for its invoices and payment links. By default it is your main ZapAPI wallet; you can link a dedicated project wallet, any account wallet, or your own external wallet via NWC from Dashboard → Project → Settlement Wallet. Integrators never pass a provider id — settlement is resolved from the project.

InvoicesCopy Anchor Link

An invoice is the primitive for a one-time Lightning payment. It wraps a BOLT-11 payment request with metadata (amount, currency, description, expiry, success URL) and a lifecycle (pending → paid | expired | cancelled).

SubscriptionsCopy Anchor Link

A plan (price + interval) turns a project into a recurring-billing business. Subscribers check out on a hosted page and manage everything from a magic-link portal; renewals settle to the project's settlement wallet and failed renewals walk a grace → past_due → cancel dunning ladder. See Project Subscriptions.

CustomersCopy Anchor Link

Every settled project payment builds the project's customer CRM automatically: lifetime value, payment counts, first/last payment, segments (vip/whale/new/churned/subscribed) and private tags/notes. No imports, no sync jobs — the payment is the record.

Payment linksCopy Anchor Link

A payment link is a reusable checkout URL backed by the same invoice machinery. Use it for tip jars, donation buttons, fixed-price products and "pay-what-you-want" flows.

WebhooksCopy Anchor Link

Webhooks push events to your backend the moment something happens (invoice.paid, zap.received, subscription.renewed, …). They are signed (HMAC-SHA256, Stripe-style t=,v1= scheme), retried with exponential backoff, and replayable from the dashboard.

The lifecycle of a paymentCopy Anchor Link

Idempotency, pagination, errorsCopy Anchor Link

Three cross-cutting concerns apply to every endpoint — read these once and the whole API becomes predictable:

• Idempotency — safe retries with Idempotency-Key.
• Pagination — cursor-based pagination for every list endpoint.
• Errors — deterministic error envelope with machine-readable codes.
• Rate limits — per-key and per-IP limits, with headers you can react to.

Live vs test modeCopy Anchor Link

Every key, webhook event and invoice carries a livemode flag. Test mode (zap_test_… keys) is a fully functional sandbox — use it for development, CI and end-to-end tests. See Environments.