Getting Started with NakaPay

Overview

NakaPay provides a developer-friendly API and tools to create and manage Bitcoin Lightning payment requests. Our service supports both custodial and non-custodial payment modes, automatically selecting the best approach based on your account configuration.

This guide covers:

• Obtaining your API Key.
• Setting up the NakaPay SDK or making direct API calls.
• Creating your first payment request.
• Checking the status of a payment.

Prerequisites

• A NakaPay account. If you don't have one, sign up here.
• Your NakaPay API Key (found in your dashboard after login).
• For SDK usage: A Node.js environment if you plan to use our server-side SDK.
• Familiarity with making HTTP requests if you plan to interact with the API directly.

Step 1: Obtain Your API Key

Your API key is crucial for authenticating your requests to the NakaPay API.

1. Log in to your NakaPay Dashboard.
2. Navigate to the API Keys section.
3. Copy your secret API key. Treat this key like a password and keep it secure.

Step 2: SDK Setup or API Integration

You can integrate with NakaPay using our official Node.js SDK nakapay-sdk or make direct API calls. The SDK provides convenience methods and TypeScript support, while direct API calls offer maximum flexibility.

To use the SDK, install it from npm:

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

Then initialize the client:

1// SECURE SDK Initialization - SERVER-SIDE ONLY
2import { NakaPay } from 'nakapay-sdk';
3
4// ✅ CORRECT: Use server-side environment variable
5const nakaPayClient = new NakaPay(process.env.NAKAPAY_API_KEY);
6
7// ❌ NEVER DO THIS: Client-side exposed API key
8// const nakaPayClient = new NakaPay(process.env.NEXT_PUBLIC_NAKAPAY_API_KEY);

For direct API calls, ensure you set the Authorization header correctly as described in our API Reference.

Step 3: Create a Payment Request

To receive a payment, you first need to create a payment request. This will generate a Lightning invoice that customers can pay. NakaPay automatically determines whether to use your connected wallet (non-custodial) or our managed system (custodial) based on your account configuration.

You'll make a POST request to the /api/v1/payment-requests endpoint. See the API Reference for Create Payment Request for full details on the request body and response.

Example using fetch on a server:

1async function createNakaPayInvoice() {
2  // ✅ SECURE: Get API key from server environment variable only
3  const apiKey = process.env.NAKAPAY_API_KEY; // Never hardcode or use client-side
4  const nakaPayApiBase = 'https://api.nakapay.app'; // NakaPay API base URL
5
6  if (!apiKey) {
7    throw new Error('NAKAPAY_API_KEY environment variable is required');
8  }
9
10  try {
11    const response = await fetch(`${nakaPayApiBase}/api/v1/payment-requests`, {
12      method: 'POST',
13      headers: {
14        'Content-Type': 'application/json',
15        'Authorization': `Bearer ${apiKey}`
16      },
17      body: JSON.stringify({
18        amount: 5000, // Amount in satoshis
19        description: 'Coffee for Cline',
20        metadata: { orderId: 'order_123' }
21      })
22    });
23
24    if (!response.ok) {
25      const errorData = await response.json();
26      throw new Error(errorData.message || `HTTP error! status: ${response.status}`);
27    }
28
29    const paymentData = await response.json();
30    console.log('Payment Request Created:', paymentData);
31    // paymentData will contain { id, invoice, status, etc. }
32    // Use paymentData.invoice to display a QR code or provide to the user.
33    return paymentData;
34
35  } catch (error) {
36    console.error('Error creating payment request:', error);
37    // Handle errors appropriately in your application
38  }
39}
40
41// Example usage:
42// createNakaPayInvoice().then(data => {
43//   if (data) { /* Display QR from data.invoice */ }
44// });

Step 4: Check Payment Status

After creating a payment request, you might want to check its status (e.g., pending, completed, expired). You can do this by making a GET request to /api/v1/payment-requests/:id/status or /api/v1/payment-requests/:id for full details.

Refer to the Get Payment Status and Get Payment Request by ID sections in the API reference.

Alternatively, and often preferably, you can use Webhooks to be notified automatically when a payment status changes.

Next Steps

Here are some resources to dive deeper:

• Live Examples: See complete implementations like our LightMarket showcase.
• Full API Reference: Detailed information for all API endpoints.
• SDK Guide: (If applicable) Learn how to use our official SDKs.
• Webhooks Guide: Set up and handle real-time payment notifications.
• React Components: (If applicable) Explore ready-to-use UI components for your React application.
• FAQ: Find answers to common questions.

If you have any further questions or need assistance, please don't hesitate to contact our support team.