RaaamiePay JavaScript SDK

The official JavaScript SDK for integrating RaaamiePay payment gateway into any website or web application.

Installation

NPM / Yarn

npm install @raaami/pay
# or
yarn add @raaami/pay

CDN (Script Tag)

<script src="https://pay.raaami.com/sdk/v1/inline.js"></script>

Quick Start

Popup Mode (Recommended)

Payment happens in an overlay without leaving your site.

import RaaamiePay from '@raaami/pay';

document.getElementById('pay-btn').addEventListener('click', () => {
  RaaamiePay.popup({
    key: 'pk_live_xxxxx',
    amount: 15000, // GHS 150.00 (in pesewas)
    currency: 'GHS',
    customer: {
      email: '[email protected]',
      phone: '024XXXXXXX',
      name: 'Kofi Mensah',
    },
    description: 'Order #1234',
    channels: ['momo', 'card', 'bank'],
    metadata: { order_id: 'ORD-1234' },
    onSuccess(response) {
      console.log('Payment successful!', response.reference);
      // Verify on your server using the reference
    },
    onClose() {
      console.log('Customer closed the checkout');
    },
    onError(error) {
      console.error('Payment failed:', error.message);
    },
  });
});

Redirect Mode

Customer is sent to the hosted checkout page. They return to your redirectUrl after payment.

import RaaamiePay from '@raaami/pay';

RaaamiePay.redirect({
  key: 'pk_live_xxxxx',
  amount: 15000,
  currency: 'GHS',
  customer: { email: '[email protected]' },
  redirectUrl: 'https://yoursite.com/payment/verify',
});

Deferred Open

Create the instance first, open later.

const payment = RaaamiePay.create({
  key: 'pk_live_xxxxx',
  amount: 15000,
  customer: { email: '[email protected]' },
  onSuccess(res) { /* ... */ },
});

// Open when user clicks
document.getElementById('pay-btn').onclick = () => payment.open();

CDN / Script Tag Usage

<script src="https://pay.raaami.com/sdk/v1/inline.js"></script>
<script>
  function payWithRaaami() {
    RaaamiePay.popup({
      key: 'pk_live_xxxxx',
      amount: 15000,
      currency: 'GHS',
      customer: { email: '[email protected]' },
      onSuccess: function(response) {
        alert('Payment complete! Ref: ' + response.reference);
      },
      onClose: function() {
        alert('Checkout closed');
      }
    });
  }
</script>

<button onclick="payWithRaaami()">Pay GHS 150.00</button>

Configuration

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | key | string | ✅ | Your public key (pk_live_xxx or pk_test_xxx) | | amount | number | ✅ | Amount in smallest unit (pesewas). 15000 = GHS 150.00 | | currency | string | No | ISO currency code. Default: 'GHS' | | reference | string | No | Unique transaction ref. Auto-generated if omitted | | customer | object | No | { email, phone, name } — at least email or phone | | description | string | No | Payment description shown on checkout | | channels | array | No | Restrict payment methods: ['momo', 'card', 'bank', 'ussd', 'qr'] | | metadata | object | No | Custom key-value data sent to your webhook | | redirectUrl | string | No | Override redirect URL for this transaction | | onSuccess | function | No | Called with response when payment succeeds | | onClose | function | No | Called when customer closes the popup | | onError | function | No | Called with error details on failure | | onLoad | function | No | Called when checkout iframe is ready |

Response Object (onSuccess)

{
  reference: string;       // 'RPY-LX1K2M-A8B3C4D5'
  transactionId: string;   // 'TXN-xxxxxxxxxxxx'
  status: 'success';
  channel: 'momo' | 'card' | 'bank' | 'ussd' | 'qr';
  amount: number;          // 15000
  currency: string;        // 'GHS'
  customer: { email, phone, name };
  metadata?: object;
}

Verify Payment (Server-side)

Always verify on your backend. Never trust client-side callbacks alone.

GET https://api.raaami.com/v1/transactions/:reference/verify
Authorization: Bearer sk_live_xxxxx

Test Mode

Use pk_test_xxxxx to test without real charges.

Test card: 4084 0840 8408 4081 | Expiry: 12/30 | CVV: 408
Test MoMo: Any phone number will simulate a successful prompt.

Browser Support

Chrome 60+, Firefox 55+, Safari 12+, Edge 79+, iOS Safari 12+, Android Chrome 60+

Bundle Size

~3KB minified + gzipped. Zero dependencies.