Components

NakaPay React Components

Ready-to-use React components for seamless Bitcoin Lightning payment integration with multiple real-time notification methods.

Last updated on June 1, 2025

Quick Start with nakapay-react

🚀 Ready to Use: Our nakapay-react component library provides production-ready React components with advanced real-time payment notifications. Install with npm install nakapay-react for the easiest integration.
1npm install nakapay-react
2# or
3yarn add nakapay-react

Basic Usage

The simplest way to accept Bitcoin Lightning payments in your React app:

1import React from 'react';
2import { NakaPayButton } from 'nakapay-react';
3import 'nakapay-react/dist/styles.css';
4
5function CheckoutPage() {
6  return (
7    <div>
8      <h2>Complete Your Purchase</h2>
9      <NakaPayButton
10        amount={50000}
11        description="Product purchase"
12        onPaymentSuccess={(payment) => {
13          console.log('Payment successful!', payment);
14          window.location.href = '/success';
15        }}
16        onPaymentError={(error) => {
17          console.error('Payment failed:', error);
18        }}
19      />
20    </div>
21  );
22}

Real-time Payment Notifications

NakaPay React components support 4 different methods for real-time payment status updates:

âš¡ Ably (Recommended)

Cloud-based real-time messaging with 99.999% uptime

🔌 WebSocket

Direct connection to your webhook server

📡 Server-Sent Events

HTTP streaming for real-time updates

🔄 Polling (Fallback)

Automatic fallback when real-time methods unavailable

Simply add the appropriate props to enable real-time notifications:

1// With Ably (recommended for production)
2<NakaPayButton
3  amount={50000}
4  description="Product purchase"
5  useAbly={true}
6  ablyApiKey="your-ably-api-key"
7  onPaymentSuccess={handleSuccess}
8/>
9
10// With WebSocket connection
11<NakaPayButton
12  amount={50000}
13  description="Product purchase"
14  useWebhooks={true}
15  webhookUrl="ws://localhost:3002"
16  onPaymentSuccess={handleSuccess}
17/>
📖 Learn More: For detailed setup instructions, examples, and best practices, see our comprehensive Real-time Notifications Guide.

Advanced Integration

For more control over the payment flow, use the NakaPayModal component:

1import React, { useState } from 'react';
2import { NakaPayModal } from 'nakapay-react';
3
4function CustomCheckout() {
5  const [showModal, setShowModal] = useState(false);
6  const [payment, setPayment] = useState(null);
7
8  const handleCustomPayment = async () => {
9    try {
10      const response = await fetch('/api/create-payment', {
11        method: 'POST',
12        headers: { 'Content-Type': 'application/json' },
13        body: JSON.stringify({
14          amount: 25000,
15          description: 'Custom payment',
16          metadata: { orderId: '12345' }
17        })
18      });
19      
20      const paymentData = await response.json();
21      setPayment(paymentData);
22      setShowModal(true);
23    } catch (error) {
24      console.error('Failed to create payment:', error);
25    }
26  };
27
28  return (
29    <div>
30      <button onClick={handleCustomPayment}>
31        Custom Pay Button
32      </button>
33      
34      {showModal && payment && (
35        <NakaPayModal
36          payment={payment}
37          onClose={() => setShowModal(false)}
38          useAbly={true}
39          ablyApiKey="your-ably-api-key"
40          onPaymentSuccess={(payment) => {
41            console.log('Success!', payment);
42            setShowModal(false);
43          }}
44        />
45      )}
46    </div>
47  );
48}

Backend Setup

Your backend needs endpoints to create payments and check status using the nakapay-sdk:

1// Backend example (Express.js with nakapay-sdk)
2const express = require('express');
3const { NakaPay } = require('nakapay-sdk');
4
5const app = express();
6app.use(express.json());
7const nakaPay = new NakaPay(process.env.NAKAPAY_API_KEY);
8
9// Create payment endpoint
10app.post('/api/create-payment', async (req, res) => {
11  try {
12    const { amount, description, metadata } = req.body;
13    const payment = await nakaPay.createPaymentRequest({
14      amount, description, metadata
15    });
16    res.json(payment);
17  } catch (error) {
18    res.status(500).json({ error: error.message });
19  }
20});
21
22// Payment status endpoint (for polling fallback)
23app.get('/api/payment-status/:id', async (req, res) => {
24  try {
25    const status = await nakaPay.getPaymentStatus(req.params.id);
26    res.json(status);
27  } catch (error) {
28    res.status(500).json({ error: error.message });
29  }
30});

Component Props Reference

NakaPayButton Props

PropTypeRequiredDescription
amountnumber✓Payment amount in satoshis
descriptionstring✓Payment description
useAblyboolean-Enable Ably real-time updates
useWebhooksboolean-Use WebSocket connection
useSSEboolean-Use Server-Sent Events
onPaymentSuccessfunction-Called when payment succeeds

For complete props reference and real-time notification setup, seeReal-time Notifications Guide.

Styling

Import the default styles or customize with your own CSS:

1// Import default styles
2import 'nakapay-react/dist/styles.css';
3
4// Or provide custom styles
5<NakaPayButton
6  amount={50000}
7  description="Product purchase"
8  className="my-custom-button"
9  style={{
10    backgroundColor: '#FF6B35',
11    borderRadius: '12px',
12    padding: '16px 32px'
13  }}
14/>

Available CSS classes: .nakapay-button, .nakapay-modal-overlay, .nakapay-modal

Further Help

For more details, check out these resources: