LNTPay Docs

LNTPay Documentation

Docs Header

Get started → Quickstart

1) Introduction

What is LNTPay

LNTPay is Lightning-native payment infrastructure for micropayments. It provides API primitives to create BOLT11 invoices, track settlement, and manage balances with a clear ledger model.

What LNTPay is NOT

  • Not a multi-coin checkout
  • Not an e-commerce payment plugin
  • Not a fiat or stablecoin gateway
  • Not a fiat on/off-ramp

**Next step** See how to use these concepts in a real Lightning micropayment flow. Go to Quickstart →

When to use LNTPay

Use LNTPay when you need one or more of the following: - Pay-per-use or microtransactions (sats) - Instant settlement with Lightning - API-first payment flows - Granular balance tracking per workspace

2) Core concepts

The building blocks of Lightning-native micropayments in LNTPay.

Workspaces

A workspace groups API keys, charges, webhooks, withdrawals, and a ledger.

Charges (Lightning invoices)

Charges create BOLT11 invoices and track payment status. A paid charge credits the workspace balance.

Ledger (available vs locked balance)

The ledger tracks all balance events. Available balance can be withdrawn; locked balance is reserved (e.g., during a withdrawal).

Webhooks (events, retries, signatures)

Webhooks deliver events to your endpoint with retries. Each payload is signed so you can verify authenticity.

Withdrawals

Withdrawals pay BOLT11 invoices using your available balance.

3) Environments

Sandbox vs Production

Sandbox is for testing; production is for live payments. Data does not mix.

API keys per environment

Keys are scoped to an environment. Use sandbox keys for tests and production keys for live traffic.

4) Authentication

How LNTPay authenticates and authorizes API requests.

API keys

Authenticate using bearer tokens.

Scopes

Scopes restrict access (e.g., charges:read, charges:write).

Headers

Typical requests include: - Authorization: Bearer <API_KEY> - Content-Type: application/json - Idempotency-Key: <uuid> (for write operations)

5) Webhooks

How LNTPay notifies your system about payment events.

Event types

Events include charge status updates and webhook tests.

Payload structure

Each delivery contains an event type, event id, and a payload object.

Signature verification (conceptual)

Compute an HMAC of the raw payload with your endpoint secret and compare with the X-Signature header.

6) Errors

Error format

Responses use a consistent error object: { "error": { "code": "error_code", "message": "Human readable message" } }

Common error codes

  • insufficient_funds
  • bolt11_invalid
  • bolt11_amount_mismatch
  • rate_limit_exceeded
  • insufficient_scopes

7) Quickstarts

Pay per API request (primary)

Real flow: charge per request and unlock after charge.paid. Quickstart page 1) Create an API key with charges:write 2) Create a charge for the request cost 3) Verify payment via webhook 4) Serve the requested content

Content paywall (secondary)

Real flow: charge once and unlock content after charge.paid. 1) Create a charge for the content 2) Wait for PAID webhook 3) Unlock content for the user

Docs Footer

**Ready to build with LNTPay?** Choose how you want to continue:

**Start the Quickstart** Build a real pay-per-use Lightning flow Start the Quickstart

**Go to Portal** Create API keys and manage payments Go to Portal