Notch Pay JavaScript SDK

The Notch Pay JavaScript SDK provides a convenient way to integrate Notch Pay into your JavaScript applications, both on the client-side and server-side with Node.js.

Installation

npm
yarn
CDN

npm install notchpay-js

yarn add notchpay-js

<script src="https://cdn.jsdelivr.net/npm/notchpay-js@latest/dist/notchpay.min.js"></script>

Client-Side Usage

Initialize the SDK

import { NotchPay } from 'notchpay-js';

// Initialize with your public key
const notchpay = new NotchPay('YOUR_PUBLIC_KEY');

const { NotchPay } = require('notchpay-js');

// Initialize with your public key
const notchpay = new NotchPay('YOUR_PUBLIC_KEY');

<script>
  // The SDK is available as window.NotchPay
  const notchpay = new NotchPay('YOUR_PUBLIC_KEY');
</script>

Open Checkout

// Create a payment on your server first, then use the payment ID to open checkout
const paymentId = 'pay_123456789'; // Get this from your server

notchpay.checkout({
  paymentId: paymentId,
  onSuccess: function(transaction) {
    console.log('Payment successful:', transaction);
    // Redirect to success page or update UI
    window.location.href = '/success?reference=' + transaction.reference;
  },
  onError: function(error) {
    console.error('Payment failed:', error);
    // Show error message
  },
  onClose: function() {
    console.log('Checkout closed');
    // Handle checkout closure
  }
});

Inline Checkout

You can also embed the checkout directly in your page:

notchpay.inlineCheckout({
  paymentId: paymentId,
  container: '#checkout-container', // CSS selector for the container element
  onSuccess: function(transaction) {
    console.log('Payment successful:', transaction);
  },
  onError: function(error) {
    console.error('Payment failed:', error);
  }
});

<!-- Add this to your HTML -->
<div id="checkout-container"></div>

Payment Button

Create a payment button with minimal code:

notchpay.createButton({
  amount: 5000,
  currency: 'XAF',
  customer: {
    email: 'customer@example.com'
  },
  reference: 'order_123',
  container: '#payment-button-container',
  text: 'Pay Now',
  className: 'my-custom-button-class'
});

<!-- Add this to your HTML -->
<div id="payment-button-container"></div>

Server-Side Usage (Node.js)

Initialize the SDK

const { NotchPayAPI } = require('notchpay-js');

// Initialize with your secret key
const notchpay = new NotchPayAPI('YOUR_SECRET_KEY');

// For endpoints requiring advanced authentication
const notchpayWithGrant = new NotchPayAPI('YOUR_SECRET_KEY', {
  grantKey: 'YOUR_PRIVATE_KEY'
});

Create a Payment

async function createPayment() {
  try {
    const payment = await notchpay.payments.create({
      amount: 5000,
      currency: 'XAF',
      customer: {
        email: 'customer@example.com',
        name: 'John Doe'
      },
      reference: 'order_123',
      callback: 'https://example.com/callback',
      description: 'Payment for Order #123'
    });
    
    console.log('Payment created:', payment);
    return payment;
  } catch (error) {
    console.error('Error creating payment:', error);
    throw error;
  }
}

Retrieve a Payment

async function getPayment(reference) {
  try {
    const payment = await notchpay.payments.retrieve(reference);
    console.log('Payment retrieved:', payment);
    return payment;
  } catch (error) {
    console.error('Error retrieving payment:', error);
    throw error;
  }
}

List Payments

async function listPayments() {
  try {
    const payments = await notchpay.payments.list({
      limit: 10,
      page: 1,
      status: 'complete'
    });
    
    console.log('Payments retrieved:', payments);
    return payments;
  } catch (error) {
    console.error('Error listing payments:', error);
    throw error;
  }
}

Create a Transfer

async function createTransfer() {
  try {
    const transfer = await notchpayWithGrant.transfers.create({
      amount: 5000,
      currency: 'XAF',
      beneficiary: {
        name: 'John Doe',
        phone: '+237600000000'
      },
      description: 'Salary payment',
      reference: 'transfer_123'
    });
    
    console.log('Transfer created:', transfer);
    return transfer;
  } catch (error) {
    console.error('Error creating transfer:', error);
    throw error;
  }
}

Check Balance

async function checkBalance() {
  try {
    const balance = await notchpayWithGrant.balance.retrieve();
    console.log('Balance:', balance);
    return balance;
  } catch (error) {
    console.error('Error checking balance:', error);
    throw error;
  }
}

Express.js Integration Example

Here’s a complete example of integrating Notch Pay with an Express.js application:

const express = require('express');
const { NotchPayAPI } = require('notchpay-js');
const app = express();

// Initialize Notch Pay SDK
const notchpay = new NotchPayAPI('YOUR_SECRET_KEY');

// Parse JSON request body
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Serve static files
app.use(express.static('public'));

// Create a payment
app.post('/create-payment', async (req, res) => {
  try {
    const { amount, email, name } = req.body;
    
    const payment = await notchpay.payments.create({
      amount: parseInt(amount),
      currency: 'XAF',
      customer: {
        email,
        name
      },
      reference: `order_${Date.now()}`,
      callback: `${req.protocol}://${req.get('host')}/payment-callback`,
      description: 'Payment from Express.js app'
    });
    
    res.json({ success: true, payment });
  } catch (error) {
    console.error('Error creating payment:', error);
    res.status(500).json({ success: false, error: error.message });
  }
});

// Payment callback
app.get('/payment-callback', async (req, res) => {
  try {
    const { reference } = req.query;
    
    // Verify payment status
    const payment = await notchpay.payments.retrieve(reference);
    
    if (payment.transaction.status === 'complete') {
      // Payment complete, fulfill the order
      res.send(`
        <html>
          <body>
            <h1>Payment Complete!</h1>
            <p>Thank you for your payment of ${payment.transaction.amount} ${payment.transaction.currency}</p>
            <p>Reference: ${payment.transaction.reference}</p>
            <a href="/">Return to Home</a>
          </body>
        </html>
      `);
    } else {
      // Payment not complete
      res.send(`
        <html>
          <body>
            <h1>Payment Not Completed</h1>
            <p>Status: ${payment.transaction.status}</p>
            <p>Reference: ${payment.transaction.reference}</p>
            <a href="/">Return to Home</a>
          </body>
        </html>
      `);
    }
  } catch (error) {
    console.error('Error verifying payment:', error);
    res.status(500).send('Error verifying payment');
  }
});

// Webhook endpoint
app.post('/webhooks/notchpay', (req, res) => {
  const event = req.body;
  
  console.log('Received webhook event:', event.type);
  
  // Process the event based on its type
  switch (event.type) {
    case 'payment.complete':
      // Handle completed payment
      console.log(`Payment ${event.data.reference} completed`);
      break;
      
    case 'payment.failed':
      // Handle failed payment
      console.log(`Payment ${event.data.reference} failed`);
      break;
      
    // Handle other event types...
  }
  
  // Always return a 200 response quickly
  res.status(200).send('Webhook received');
});

// Start the server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

React Integration Example

Here’s how to integrate Notch Pay with a React application:

import React, { useState } from 'react';
import { NotchPay } from 'notchpay-js';

// Initialize Notch Pay SDK
const notchpay = new NotchPay('YOUR_PUBLIC_KEY');

function PaymentForm() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);
  
  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);
    setError(null);
    
    try {
      // Create payment on your server
      const response = await fetch('/api/create-payment', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          amount: 5000,
          email: 'customer@example.com',
          name: 'John Doe'
        }),
      });
      
      const data = await response.json();
      
      if (!data.success) {
        throw new Error(data.error || 'Failed to create payment');
      }
      
      // Open checkout
      notchpay.checkout({
        paymentId: data.payment.transaction.id,
        onSuccess: function(transaction) {
          console.log('Payment successful:', transaction);
          // Redirect or update UI
          window.location.href = `/success?reference=${transaction.reference}`;
        },
        onError: function(error) {
          console.error('Payment failed:', error);
          setError('Payment failed: ' + error.message);
        },
        onClose: function() {
          console.log('Checkout closed');
        }
      });
    } catch (error) {
      console.error('Error:', error);
      setError(error.message);
    } finally {
      setLoading(false);
    }
  };
  
  return (
    <div className="payment-form">
      <h2>Complete Your Payment</h2>
      
      {error && (
        <div className="error-message">
          {error}
        </div>
      )}
      
      <form onSubmit={handleSubmit}>
        <button 
          type="submit" 
          disabled={loading}
          className="payment-button"
        >
          {loading ? 'Processing...' : 'Pay 5,000 XAF'}
        </button>
      </form>
    </div>
  );
}

export default PaymentForm;

API Reference

The JavaScript SDK provides access to all Notch Pay API endpoints:

Payments

notchpay.payments.create(data) - Create a payment
notchpay.payments.retrieve(reference) - Retrieve a payment
notchpay.payments.list(params) - List payments
notchpay.payments.cancel(reference) - Cancel a payment

Transfers

notchpay.transfers.create(data) - Create a transfer
notchpay.transfers.retrieve(reference) - Retrieve a transfer
notchpay.transfers.list(params) - List transfers
notchpay.transfers.cancel(reference) - Cancel a transfer
notchpay.transfers.createBulk(data) - Create a bulk transfer

Customers

notchpay.customers.create(data) - Create a customer
notchpay.customers.retrieve(id) - Retrieve a customer
notchpay.customers.update(id, data) - Update a customer
notchpay.customers.list(params) - List customers
notchpay.customers.delete(id) - Delete a customer

Beneficiaries

notchpay.beneficiaries.create(data) - Create a beneficiary
notchpay.beneficiaries.retrieve(id) - Retrieve a beneficiary
notchpay.beneficiaries.update(id, data) - Update a beneficiary
notchpay.beneficiaries.list(params) - List beneficiaries
notchpay.beneficiaries.delete(id) - Delete a beneficiary

Balance

notchpay.balance.retrieve() - Check balance
notchpay.balance.retrieveCurrency(currency) - Check balance for a specific currency
notchpay.balance.history(params) - List balance history

Webhooks

notchpay.webhooks.create(data) - Create a webhook
notchpay.webhooks.retrieve(id) - Retrieve a webhook
notchpay.webhooks.update(id, data) - Update a webhook
notchpay.webhooks.list(params) - List webhooks
notchpay.webhooks.delete(id) - Delete a webhook

Error Handling

The SDK throws detailed errors that you can catch and handle:

try {
  const payment = await notchpay.payments.create({
    // Payment data
  });
} catch (error) {
  if (error.type === 'validation_error') {
    console.error('Validation error:', error.errors);
  } else if (error.type === 'authentication_error') {
    console.error('Authentication error:', error.message);
  } else {
    console.error('Unexpected error:', error.message);
  }
}

TypeScript Support

The SDK includes TypeScript definitions for all methods and objects:

import { NotchPay, Payment, Customer, Transfer } from 'notchpay-js';

const notchpay = new NotchPay('YOUR_PUBLIC_KEY');

async function createTypedPayment(): Promise<Payment> {
  const payment = await notchpay.payments.create({
    amount: 5000,
    currency: 'XAF',
    customer: {
      email: 'customer@example.com'
    } as Customer,
    reference: 'order_123'
  });
  
  return payment;
}

API Reference

Complete API documentation

PHP SDK

Integrate with PHP applications

Python SDK

Integrate with Python applications

SDKs

Plugins

Integrations

JavaScript SDK

Notch Pay JavaScript SDK

Installation

Client-Side Usage

Initialize the SDK

Open Checkout

Inline Checkout

Payment Button

Server-Side Usage (Node.js)

Initialize the SDK

Create a Payment

Retrieve a Payment

List Payments

Create a Transfer

Check Balance

Express.js Integration Example

React Integration Example

API Reference

Payments

Transfers

Customers

Beneficiaries

Balance

Webhooks

Error Handling

TypeScript Support

API Reference

PHP SDK

Python SDK

​Notch Pay JavaScript SDK

​Installation

​Client-Side Usage

​Initialize the SDK

​Open Checkout

​Inline Checkout

​Payment Button

​Server-Side Usage (Node.js)

​Initialize the SDK

​Create a Payment

​Retrieve a Payment

​List Payments

​Create a Transfer

​Check Balance

​Express.js Integration Example

​React Integration Example

​API Reference

​Payments

​Transfers

​Customers

​Beneficiaries

​Balance

​Webhooks

​Error Handling

​TypeScript Support

​Related Resources

API Reference

PHP SDK

Python SDK

Notch Pay JavaScript SDK

Installation

Client-Side Usage

Initialize the SDK

Open Checkout

Inline Checkout

Payment Button

Server-Side Usage (Node.js)

Initialize the SDK

Create a Payment

Retrieve a Payment

List Payments

Create a Transfer

Check Balance

Express.js Integration Example

React Integration Example

API Reference

Payments

Transfers

Customers

Beneficiaries

Balance

Webhooks

Error Handling

TypeScript Support

Related Resources