Non-Custodial Payments
Take full control of your Lightning payments by connecting your own wallet to NakaPay. Learn about the benefits, setup process, and considerations of using non-custodial payments.
Overview
NakaPay supports two payment modes: custodial (NakaPay-managed) and non-custodial (your own wallet). Non-custodial payments give you complete control over your funds by connecting your own Lightning wallet to receive payments directly.
What is Non-Custodial?
Custodial vs Non-Custodial
Non-Custodial (Your Wallet)
- ✓You control your private keys
- ✓Payments go directly to your wallet
- ✓Faster settlement and efficient processing
- ✓No counterparty risk
- ✓Instant settlement
Custodial (NakaPay Managed)
- •NakaPay manages the wallet
- •Funds held temporarily by NakaPay
- •Easier setup and management
- •Higher reliability
- •No wallet management required
Benefits of Non-Custodial
Efficient Processing
More efficient payment processing with direct wallet integration and streamlined fee collection.
Full Control
You maintain complete ownership and control of your funds at all times.
Instant Settlement
Payments are settled directly to your wallet immediately upon payment.
Enhanced Security
No counterparty risk - your funds are never held by a third party.
Getting Started
Setting up non-custodial payments requires connecting a compatible Lightning wallet to NakaPay. Here's how to get started:
Step 1: Choose a Compatible Wallet
You need a Lightning wallet that supports Nostr Wallet Connect (NWC). Popular options include:
⚡ Alby
Browser extension wallet with excellent NWC support
⚡ Zeus
Mobile Lightning wallet with built-in NWC
💡 LNbits
Self-hosted Lightning wallet solution
Step 2: Generate Connection String
In your wallet, create a new NWC connection with the required permissions. Your wallet will generate a connection string that looks like:
Required Permissions
- •
make_invoice- Create payment requests - •
get_balance- Check wallet balance - •
pay_invoice- Pay NakaPay fees
Step 3: Connect to NakaPay
Go to your Wallet Settings page and paste your connection string. NakaPay will test the connection and verify permissions.
Ready to Go!
How It Works
The non-custodial payment flow is designed to be transparent and efficient:
Customer Pays
Customer scans QR code and pays the full amount directly to your Lightning wallet
Fee Collection
NakaPay automatically withdraws the agreed fee amount using your wallet's permissions
You Keep the Rest
The remaining amount stays in your wallet under your complete control
Important Considerations
While non-custodial payments offer many benefits, there are some trade-offs to consider:
Responsibilities
Reliability Considerations
Since your wallet needs to be online to receive payments, ensure your wallet provider has good uptime. If payment reliability is critical for your business, you may want to monitor your wallet's availability and consider using wallets with high reliability guarantees.
Security Best Practices
- Only grant the minimum required permissions (
make_invoice,get_balance,pay_invoice) - Keep your wallet software updated and secure
- Monitor your wallet balance and transactions regularly
- Never share your connection string with untrusted services
- Use strong passwords and two-factor authentication for your wallet
Troubleshooting
Connection Test Fails
If the connection test fails, check:
- Your wallet is online and accessible
- The connection string is copied correctly
- All required permissions are granted
- Your wallet has sufficient inbound liquidity
- The relay server specified in your connection string is accessible
Payments Failing
If customers can't pay you:
- Check your wallet's online status
- Verify you have inbound liquidity for the payment amount
- Check if your relay server is accessible
- Review your wallet's connection logs for errors
Fee Collection Issues
If fee collection fails:
- Ensure your wallet has the
pay_invoicepermission - Check your wallet has sufficient outbound liquidity
- Verify your wallet is online and responsive
- Check for any spending limits in your wallet configuration
Frequently Asked Questions
What happens if my wallet goes offline?
If your wallet is offline when someone tries to pay, the payment will fail. Most modern wallets have good uptime. You can monitor your wallet's connectivity and consider using wallets with high reliability guarantees.
Can I switch back to custodial mode?
Yes, you can disconnect your wallet at any time from your dashboard settings. Payments will automatically fall back to custodial mode immediately.
What wallets are supported?
Any wallet that supports Nostr Wallet Connect (NWC) including Alby, Zeus, LNbits, and many others. The wallet must support the required NWC permissions for invoice creation and payment.
Are there any fees for using non-custodial mode?
NakaPay charges the same platform fees regardless of mode. However, non-custodial mode may provide better overall efficiency due to direct settlement and streamlined processing.
Do I need to change my existing integrations?
No! Your existing SDK integrations, API calls, and customer payment flows continue to work exactly the same. The choice between custodial and non-custodial is handled automatically by NakaPay based on your wallet connection status.
How do I monitor my non-custodial payments?
Your NakaPay dashboard shows all payments regardless of mode. You can also monitor transactions directly in your Lightning wallet. Webhooks and API responses include information about whether each payment was processed in custodial or non-custodial mode.
Get Started
Ready to take control of your Lightning payments? Here's what to do next:
- Choose and set up a compatible Lightning wallet with NWC support
- In your wallet, create a new NWC connection with the required permissions
- Connect your wallet in your NakaPay dashboard
- Test the connection and start receiving non-custodial payments