NakaPay API Reference

Authentication

All API requests must be authenticated using an API key. Obtain your API key from your NakaPay dashboard. The API key must be included in the Authorization header of your requests as a Bearer token.

1Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your actual secret API key.

API Version

The current NakaPay API version is v1. All endpoints are prefixed with /api/v1/. The base URL for the NakaPay API is: https://api.nakapay.app

Payment Requests

The base URL for payment request endpoints is: /api/v1/payment-requests

Create a Payment Request

Creates a new payment request (e.g., a Lightning invoice to be paid).

Endpoint: POST /api/v1/payment-requests

Request Body

The request body must be a JSON object with the following fields:

• amount (number, required): The amount in satoshis. Minimum value is 21 sats. See Fees section for fee structure.
• description (string, required): A description for the payment (max 255 characters).
• destinationWallet (string, required): Lightning address where payments should be sent. For non-custodial payments (NWC connected), this is stored for records but payments go directly to your connected wallet address.
• metadata (object, optional): An object to store any custom key-value pairs, like an order ID or customer ID.
• expiresIn (number, optional): The duration in seconds for which the payment request is valid. Defaults to 3600 seconds (1 hour).

Example Request Body:

1{
2  "amount": 10000,
3  "description": "Order #12345 - T-shirt",
4  "destinationWallet": "payments@mybusiness.com",
5  "metadata": {
6    "orderId": "12345",
7    "customerId": "cust_abc123"
8  },
9  "expiresIn": 1800
10}

Responses

• 201 Created: Payment request created successfully. The response body will contain the details of the created payment request, including its ID and the Lightning invoice (if applicable).

  1{
  2  "id": "pr_xxxxxxxxxxxxxxxxx",
  3  "status": "pending",
  4  "amount": 10000,
  5  "description": "Order #12345 - T-shirt",
  6  "invoice": "lnbc100u1pjr....", // The actual Lightning invoice
  7  "paymentHash": "a1b2c3d4...", // Payment hash for tracking
  8  "expiresAt": "2025-05-22T12:30:00.000Z",
  9  "isNwc": false, // Payment mode: true = non-custodial, false = custodial
  10  "feeAmount": 50, // Fee amount in satoshis
  11  "feePercentage": 0.5, // Fee percentage applied
  12  "metadata": {
  13    "orderId": "12345",
  14    "customerId": "cust_abc123"
  15  },
  16  "createdAt": "2025-05-22T11:30:00.000Z",
  17  "updatedAt": "2025-05-22T11:30:00.000Z"
  18}

• 400 Bad Request: Invalid input data (e.g., missing required fields, invalid amount). The response body may contain details about the error.
• 401 Unauthorized: API key is missing, invalid, or does not have permissions to perform this action.

Get Payment Request by ID

Retrieves the details of a specific payment request by its ID.

Endpoint: GET /api/v1/payment-requests/:id

Replace :id with the actual payment request ID.

Responses

• 200 OK: Successfully retrieved the payment request. The response body will be similar to the success response of the create endpoint.

  1{
  2  "id": "pr_xxxxxxxxxxxxxxxxx",
  3  "status": "completed", // or "pending", "expired", "failed"
  4  "amount": 10000,
  5  "description": "Order #12345 - T-shirt",
  6  "invoice": "lnbc100u1pjr....",
  7  "paymentHash": "a1b2c3d4...",
  8  "expiresAt": "2025-05-22T12:30:00.000Z",
  9  "isNwc": true, // Indicates this was processed non-custodially
  10  "nwcRelay": "wss://relay.getalby.com/v1", // NWC relay used (if applicable)
  11  "preimage": "def456...", // Payment preimage (if completed)
  12  "feeAmount": 50,
  13  "feePercentage": 0.5,
  14  "metadata": {
  15    "orderId": "12345",
  16    "customerId": "cust_abc123"
  17  },
  18  "createdAt": "2025-05-22T11:30:00.000Z",
  19  "updatedAt": "2025-05-22T12:05:00.000Z"
  20}

• 401 Unauthorized: API key is missing or invalid.
• 404 Not Found: Payment request with the specified ID was not found.

Get Payment Request Status

Retrieves the current status of a specific payment request by its ID.

Endpoint: GET /api/v1/payment-requests/:id/status

Replace :id with the actual payment request ID.

Responses

• 200 OK: Successfully retrieved the payment status.

  1{
  2  "status": "completed" // Possible values: "pending", "completed", "expired", "failed"
  3}

• 401 Unauthorized: API key is missing or invalid.
• 404 Not Found: Payment request with the specified ID was not found.

Payment Modes

NakaPay supports both custodial and non-custodial payment processing. The mode is automatically selected based on your account configuration, and payment responses include fields to indicate which mode was used.

Payment Mode Fields

All payment request responses include these fields to indicate the processing mode:

• isNwc (boolean): Indicates the payment mode
  • true - Processed non-custodially using your connected Lightning wallet
  • false - Processed custodially using NakaPay's managed system
• nwcRelay (string, optional): The Nostr relay used for non-custodial payments. Only present when isNwc is true.
• preimage (string, optional): The payment preimage, available after successful completion. Useful for proof of payment and debugging.

Fee Structure

NakaPay charges a small fee on each payment to cover Lightning Network routing costs:

Minimum Payment

The minimum payment amount is 21 sats. Payments below this amount will be rejected with a 400 Bad Request error. This ensures the fee never exceeds ~50% of the payment amount.

Fee Examples

The base fee for small payments helps cover Lightning Network routing costs, which include fixed per-hop fees that don't scale with payment size.

Fee Response Fields

All payment responses include fee information:

• feeAmount (number): The fee amount in satoshis
• feePercentage (number): The fee percentage applied to this payment

Note: Fee amounts are the same regardless of payment mode. The difference lies in how fees are collected: custodial payments deduct fees before forwarding, while non-custodial payments collect fees separately.

For more detailed guides on integrating, including SDK usage and webhook setup, please see our Getting Started guide and other documentation sections.