Jump to

Zaptrain API

Build payments into your application.

The Zaptrain API provides a RESTful interface to create, manage, and track Bitcoin Lightning invoices. All API requests use application/json for request and response bodies.

The base URL for all API endpoints is https://zaptrain.com.

This documentation covers the v1 API. For a machine-readable OpenAPI specification, visit /api/docs/openapi.json. For interactive exploration, try the Swagger UI.

Authentication

API Key (Bearer Token)

All v1 API endpoints accept Bearer token authentication using API keys. Generate an API key from your account settings and include it in theAuthorization header.

Authorization: Bearer isvk_abc123def456...

API keys are prefixed with isvk_. They are shown only once when created. If you lose an API key, delete it and create a new one in your settings.

Session Cookie

Browser sessions authenticated via the Zaptrain web app automatically include session cookies. API requests from your browser will use these credentials automatically. This is useful for testing in a browser console or integrating Zaptrain with a web app served on the same domain.

Error Responses

If authentication fails, the API returns a 401 Unauthorized status:

{
  "error": "Unauthorized"
}

GET/api/v1/users/me

Get merchant profile

Returns the authenticated merchant's profile including branding settings and account info.

Examples

{
  "id": 1,
  "name": "Acme Corp",
  "email": "hello@acme.com",
  "brand_name": "Acme",
  "brand_color": "#d26434",
  "logo_url": "/api/logo/abc123.png",
  "default_memo": "Thank you!",
  "created_at": "2024-01-15T10:30:00Z"
}

PATCH/api/v1/users/me

Update merchant profile

Update mutable profile fields: brand name, brand color, and default memo. All other fields are ignored.

Request Body

Parameter	Type	Required	Description
brand_name	string	—	Display name for invoices
brand_color	string	—	Hex color (e.g., #d26434)
default_memo	string	—	Default text on invoices

Examples

{
  "id": 1,
  "name": "Acme Corp",
  "email": "hello@acme.com",
  "brand_name": "Acme Updated",
  "brand_color": "#1e4d8c",
  "logo_url": "/api/logo/abc123.png",
  "default_memo": "Thanks for your business!",
  "created_at": "2024-01-15T10:30:00Z"
}

GET/api/v1/users/me/usage

Get fee rate

Returns the current fee rate applied to all invoices created by this merchant.

Examples

{
  "fee_rate": 0.01,
  "fee_rate_pct": "1%",
  "description": "1% of each transaction amount"
}

GET/api/v1/invoices

List invoices

Retrieve a paginated list of invoices for the authenticated merchant, ordered by creation date (newest first).

Parameters

Parameter	In	Type	Required	Description
limit	query	integer	—	Max results to return (1–100, default 20)
offset	query	integer	—	Number of records to skip (default 0)

Examples

{
  "invoices": [
    {
      "id": 42,
      "public_id": "xK9mPqR3vN7w",
      "merchant_id": 1,
      "customer_name": "Jane Smith",
      "customer_email": "jane@example.com",
      "status": "sent",
      "currency": "SATS",
      "amount_cents": 50000,
      "memo": "Web design work",
      "due_date": "2024-04-01",
      "bolt11": "lnbc500u1p0sample...",
      "lexe_index": "abc123",
      "lexe_status": "pending",
      "lexe_status_msg": "invoice generated",
      "fee_sats": 500,
      "tax_percent": 10,
      "tax_amount_sats": 5000,
      "created_at": "2024-03-01T00:00:00Z",
      "updated_at": "2024-03-01T00:00:00Z",
      "sent_at": "2024-03-01T12:00:00Z"
    }
  ],
  "total": 23
}

POST/api/v1/invoices

Create invoice

Create a new draft invoice. The invoice is created without a payment link (BOLT11) until explicitly generated or sent.

Request Body

Parameter	Type	Required	Description
customer_name	string	Yes	Customer name
customer_email	string	Yes	Customer email address
memo	string	—	Invoice description/memo
due_date	string	—	Due date (ISO 8601 format)
items	array	Yes	Line items with description, quantity, unit_price_sats
tax_percent	number	—	Tax percentage (default 0)
tax_amount_sats	integer	—	Flat tax in satoshis (default 0)

Examples

{
  "id": 43,
  "public_id": "mK2nQpX9wP5r",
  "merchant_id": 1,
  "customer_name": "Jane Smith",
  "customer_email": "jane@example.com",
  "status": "draft",
  "currency": "SATS",
  "amount_cents": 55000,
  "memo": "Web design work",
  "due_date": "2024-04-01",
  "bolt11": null,
  "lexe_index": null,
  "lexe_status": null,
  "fee_sats": 550,
  "tax_percent": 10,
  "tax_amount_sats": 5000,
  "created_at": "2024-03-15T10:30:00Z",
  "updated_at": "2024-03-15T10:30:00Z",
  "sent_at": null
}

GET/api/v1/invoices/{id}

Get invoice

Retrieve a single invoice by its internal ID. Returns full invoice details including status, payment info, and line items.

Parameters

Parameter	In	Type	Required	Description
id	path	integer	Yes	Invoice internal ID (not public_id)

Examples

{
  "id": 42,
  "public_id": "xK9mPqR3vN7w",
  "merchant_id": 1,
  "customer_name": "Jane Smith",
  "customer_email": "jane@example.com",
  "status": "sent",
  "currency": "SATS",
  "amount_cents": 50000,
  "memo": "Web design work",
  "due_date": "2024-04-01",
  "bolt11": "lnbc500u1p0sample...",
  "lexe_index": "abc123",
  "lexe_status": "pending",
  "lexe_status_msg": "invoice generated",
  "fee_sats": 500,
  "tax_percent": 10,
  "tax_amount_sats": 5000,
  "created_at": "2024-03-01T00:00:00Z",
  "updated_at": "2024-03-01T12:00:00Z",
  "sent_at": "2024-03-01T12:00:00Z"
}

POST/api/v1/invoices/{id}/send

Send invoice email

Send invoice to customer via email. Optionally customize the email subject and message. Updates invoice status to 'sent'.

Parameters

Parameter	In	Type	Required	Description
id	path	integer	Yes	Invoice internal ID

Request Body

Parameter	In	Type	Required	Description
subject		string	—	Custom email subject
message		string	—	Custom message to include in email body

Examples

{
  "ok": true,
  "status": "sent"
}

POST/api/v1/invoices/{id}/remind

Send reminder email

Send a payment reminder to customer. Use mode='same' to resend the original email, or mode='new' to regenerate with optional custom message.

Parameters

Parameter	In	Type	Required	Description
id	path	integer	Yes	Invoice internal ID

Request Body

Parameter	Type	Required	Description
mode	string	—	'same' to resend original, 'new' to regenerate (default 'new')
subject	string	—	Custom email subject (mode='new' only)
message	string	—	Custom message (mode='new' only)

Examples

{
  "ok": true,
  "status": "sent"
}

POST/api/v1/invoices/{id}/cancel

Cancel an invoice

Soft-cancel an outstanding invoice. Preserves the invoice row and history. Paid invoices cannot be cancelled, and drafts must be deleted instead. Cancelling an already-cancelled invoice is a no-op (idempotent).

Parameters

Parameter	In	Type	Required	Description
id	path	integer	Yes	Invoice internal ID

Examples

{
  "ok": true,
  "status": "cancelled",
  "invoice": {
    "id": 42,
    "public_id": "xK9mPqR3vN7w",
    "status": "cancelled",
    "amount_cents": 50000,
    "customer_name": "Jane Smith",
    "customer_email": "jane@example.com"
  }
}

GET/api/v1/invoices/{id}/payment

Get payment status

Get payment and Lightning Network status for an invoice. Includes BOLT11 code, payment status, and finalization timestamp.

Parameters

Parameter	In	Type	Required	Description
id	path	integer	Yes	Invoice internal ID

Examples

{
  "id": 42,
  "public_id": "xK9mPqR3vN7w",
  "status": "sent",
  "bolt11": "lnbc500u1p0sample...",
  "lexe_status": "completed",
  "lexe_status_msg": "payment received",
  "lexe_finalized_at": "2024-03-02T14:30:00Z",
  "amount_sats": 50000,
  "fee_sats": 500
}

Need help? Contact us.