Frequently Asked Questions (FAQ)

NakaPay is a developer-friendly Bitcoin Lightning payment processing service. It allows businesses to easily accept Lightning Network payments on their websites and applications with minimal setup.

NakaPay supports two payment modes that are automatically selected based on your account configuration:

• Non-Custodial Mode: If you connect your own Lightning wallet via Nostr Wallet Connect (NWC), payments go directly to your wallet and you maintain full control of your funds.
• Custodial Mode: If no wallet is connected, NakaPay manages the payment process and forwards funds to your configured Lightning address.

Your integration code works exactly the same regardless of which mode is used - the routing is handled automatically.

NakaPay charges a small transaction fee, typically around 0.5%. Please refer to our main Pricing section or your service agreement for the most current fee structure.

NakaPay supports both custodial and non-custodial modes:

• Non-Custodial: If you connect your own Lightning wallet, we never hold your funds - payments go directly to your wallet.
• Custodial: If you use our managed system, funds are temporarily held and then forwarded to your Lightning address.

You can choose your preferred mode by connecting a Lightning wallet in your dashboard settings, or continue using the managed system for simplicity.

You can get your API key by signing up for a NakaPay account. Once registered, your API key will be available in your NakaPay Dashboard. Keep your API key secure, as it's used to authenticate your requests to our service.

A Lightning Address (e.g., yourname@getalby.com) is like an email address for receiving Bitcoin Lightning payments. An LNURL is a more general protocol that can be used for payments, withdrawals, and authentication. You'll need one of these for your business to receive payments via NakaPay.

Many Lightning wallets and services provide Lightning Addresses, such as:

• Alby
• Zeus
• Blixt Wallet
• Wallet of Satoshi
• Bitkit
• Breez Mobile

You configure your receiving Lightning Address or LNURL in your NakaPay account settings.

You can install our Node.js SDK using npm or yarn:

1npm install nakapay-sdk
2# or
3yarn add nakapay-sdk

For detailed instructions, please see our SDK Guide.

Currently, NakaPay does not offer a dedicated, installable React component library. However, you can easily build your own React components to interact with our service.

We recommend creating a secure backend endpoint in your application that uses the NakaPay Node.js SDK or direct API calls. Your React frontend can then communicate with this backend endpoint.

For guidance and examples on how to structure such components, please refer to our Integrating with React Applications Guide.

1. API Key: Ensure you are using a valid API key and it's correctly used in your backend/SDK configuration.
2. Amount & Description: Make sure the amount is a positive integer (sats) and the description is provided when creating payment requests.
3. Destination Wallet: Verify that your destination Lightning Address or LNURL is correctly configured in your NakaPay settings and/or passed to the payment function.
4. Console Errors: Check your browser's developer console (for frontend issues) or your server logs (for SDK/API usage) for any error messages.
5. API Connectivity: Ensure your server can reach the NakaPay API endpoint. Firewalls or network issues could be a problem.
6. SDK Version: Make sure you are using the latest compatible version of the Node.js SDK.

1. Webhook URL: Confirm your Webhook URL is correctly set in your NakaPay Dashboard or via API/SDK registration. It must be a publicly accessible HTTPS URL.
2. Server Status: Ensure your webhook handling server is running and accessible from the internet. Use tools like ngrok for local testing.
3. Response Code: Your endpoint must respond with a 2xx status code (e.g., 200 OK) to acknowledge receipt. If NakaPay receives an error or timeout, it may stop sending or retry later.
4. Firewall/Security: Check if any firewalls or security groups are blocking incoming POST requests from NakaPay servers.
5. Payload Processing: Ensure your server can correctly parse the JSON payload.
6. Signature Verification: If you're verifying signatures (highly recommended), ensure your webhook secret is correct and the verification logic is sound. See the Webhooks Guide.

• Incorrect Secret: Double-check that you are using the correct webhook secret provided by NakaPay.
• Raw Body: Ensure you are using the raw, unparsed request body to generate the signature for comparison. Any modification to the body string (even whitespace changes) will result in a mismatch.
• Algorithm: Verify you are using HMAC with SHA-256, as specified in our documentation.
• Encoding: Ensure consistent character encoding (UTF-8 is standard).

Payment responses and webhook payloads include an isNwc field that indicates the payment mode:

• isNwc: true - Payment was processed non-custodially using your connected wallet
• isNwc: false - Payment was processed custodially using NakaPay's managed system

You can also see this information in your dashboard and when listing payment history via the API.

No! Your integration code remains exactly the same regardless of payment mode. NakaPay automatically selects the appropriate mode based on whether you have a wallet connected. The API endpoints, request formats, and response structures are identical for both modes.

Yes, you can switch modes at any time:

• To Non-Custodial: Connect a Lightning wallet in your wallet settings
• To Custodial: Disconnect your wallet from the same settings page

Changes take effect immediately for new payment requests. Existing pending payments continue using their original mode.

Any Lightning wallet that supports Nostr Wallet Connect (NWC) can be used for non-custodial payments. Popular options include:

• Alby (browser extension)
• Zeus (mobile wallet)
• LNbits (self-hosted)
• Many others - see our non-custodial guide for a complete list

Yes, the NakaPay API is rate-limited to protect the service. Typically, this is around 100 requests per minute per API key. If you exceed this limit, you'll receive a 429 Too Many Requests HTTP error. If you anticipate needing higher limits, please contact support.

The minimum payment amount is typically 1 satoshi. Maximum amounts may depend on Lightning Network constraints or specific wallet limitations. Our service itself aims to be flexible, but practical limits of the Lightning Network apply.

If you can't find an answer in our documentation:

• Check our main website nakapay.app for updates.
• Email our support team at support@nakapay.app.
• Join our community on Discord (if a link is provided on our main site).
• Check for existing issues or open a new one on our GitHub repository (if public).