CoffePay SDK for JavaScript/TypeScript

Integrating M-Pesa payments into your web application has never been easier. This SDK provides a simple interface to initiate payments and listen for real-time status updates via WebSockets.

[!TIP] Resource Optimized: The SDK uses "On-Demand" connections. It only opens the WebSocket tunnel when a payment is actually in progress and closes it immediately after completion, saving battery and data for your users.

Installation

npm install @coffebit/coffepay_sdk

Usage

1. Basic Integration (Vanilla JS/TS)

import { CoffePayClient, CoffePayTunnel } from '@coffebit/coffepay_sdk';

const client = new CoffePayClient('your-license-key');
const tunnel = new CoffePayTunnel('your-license-key');

// 1. Listen for status updates
tunnel.listen((event) => {
  if (event.status === 'success') {
    alert('Payment successful!');
  } else if (event.status === 'error') {
    alert(`Payment failed: ${event.error}`);
  }
});

// 2. Initiate payment
async function handlePay() {
  try {
    const response = await client.initiatePayment({
      amount: 10,
      msisdn: '840000000',
      reference: 'ORDER-123'
    });
    console.log('Payment initiated:', response.provider_ref);
  } catch (err) {
    console.error('Initiation failed:', err);
  }
}

2. React Integration

import { useCoffePay } from '@coffebit/coffepay_sdk/react';

function PaymentButton() {
  const { pay, isLoading, status, error } = useCoffePay({
    licenseKey: 'your-license-key',
    onSuccess: (event) => console.log('Paid!', event),
    onError: (err) => console.error('Error', err),
  });

  return (
    <div>
      <button 
        disabled={isLoading}
        onClick={() => pay({ amount: 10, msisdn: '840000000', reference: 'REF-1' })}
      >
        {isLoading ? 'Processing...' : 'Pay with M-Pesa'}
      </button>

      {status === 'success' && <p>✅ Payment Successful!</p>}
      {status === 'error' && <p>❌ Error: {error}</p>}
    </div>
  );
}

API Reference

CoffePayClient

• initiatePayment(params): Sends a payment request to the merchant's customer.

CoffePayTunnel

• listen(callback): Connects to the real-time notification service.
• stop(): Disconnects the tunnel.

useCoffePay(options) (React)

• pay(params): Initiates payment and manages state.
• isLoading: Boolean state for the current request.
• status: 'idle' | 'pending' | 'success' | 'error'.
• transaction: The full payment event data.