JS SDK - API Documentation

Overview

The Genesyspay JS SDK allows you to accept payments directly from your website. It opens a secure checkout modal (or redirects to our hosted page) without the payer leaving your site. The SDK handles the entire payment UI — you only need to provide your public key, amount, and a few callbacks.

Installation

Include the SDK script in your page. Place it before your closing </body> tag or in the <head>:

<script src="https://checkout.genesyspay.com/v1/sdk/js/checkout.js"></script>

This exposes the global GenesyspayCheckout object.

Quick Start

<button id="pay-btn">Pay Now</button>

<script src="https://checkout.genesyspay.com/v1/sdk/js/checkout.js"></script>
<script>
  document.getElementById('pay-btn').addEventListener('click', function () {
    var checkout = GenesyspayCheckout.create({
      pub_key: 'YOUR_PUBLIC_KEY',
      amount: 5000,
      currency: 'CDF',
      country: 'CD',
      tx_ref: 'order-' + Date.now(),
      description: 'Purchase #12345',
      redirect_url: 'https://yoursite.com/payment/callback',
      callback_url: 'https://yoursite.com/webhook',
      payer_name: 'John Doe',
      payer_email: '[email protected]',
      payer_phone: '0707070707',

      onSuccess: function (data) {
     
        
      },
      onError: function (error) {
        console.error('Payment failed', error);
      },
      onClose: function () {
        console.log('Checkout modal closed');
      }
    });

    checkout.open();
  });
</script>

Configuration Options

Pass a configuration object to GenesyspayCheckout.create(config):

Parameter	Type	Required	Description
`pub_key`	string	Required	Your merchant public key.
`amount`	number	Required	Amount to charge.
`currency`	string	Required	3-letter ISO currency code (e.g. `CDF`).
`tx_ref`	string	Required	Your unique transaction reference.
`country`	string	Optional	2 or 3-letter ISO country code.
`allowed_channels`	string	Optional	Comma-separated list of allowed payment channels. Values: `mobile_money`, `card`. Example: `'mobile_money,card'`.
`channel`	string	Optional	Pre-select a channel (e.g. `mobile_money`).
`method`	string	Optional	Pre-select a specific payment method slug.
`description`	string	Optional	Payment description.
`redirect_url`	string	Optional	URL to redirect after payment (used in redirect mode and as fallback).
`callback_url`	string	Optional	Webhook URL to receive the final transaction status.
`bearer`	string	Optional	Fee bearer: `customer` (default) or `merchant`.
`payer_name`	string	Optional	Payer's full name.
`payer_email`	string	Optional	Payer's email address.
`payer_phone`	string	Optional	Payer's phone number.
`extras`	object	Optional	Arbitrary key-value metadata.
`onSuccess`	function	Optional	Called when payment succeeds. Receives `{ transaction_id }`.
`onError`	function	Optional	Called when payment fails. Receives an `Error` object.
`onClose`	function	Optional	Called when the payer manually closes the modal.

Methods

`checkout.open()` — Modal Mode

Opens the checkout as a full-screen modal overlay on your page. The payer stays on your site and the payment form loads inside an iframe.

var checkout = GenesyspayCheckout.create({ ... });
checkout.open();

`checkout.redirect()` — Redirect Mode

Redirects the payer to the hosted checkout page in the current browser tab. After payment, the payer is redirected back to your redirect_url with query parameters appended (status, tx_ref, transaction_id).

var checkout = GenesyspayCheckout.create({ ... });
checkout.redirect();

ℹ️ Note: In redirect mode, onSuccess, onError, and onClose callbacks are not used — the result is communicated via the redirect URL parameters.

Callback Behavior (Modal Mode)

After payment, the SDK posts a message event from the checkout iframe to the parent window:

Event Type	Triggered When	Callback
`CHECKOUT_SUCCESS`	Payment completed successfully.	`onSuccess(data)`
`CHECKOUT_FAILED`	Payment failed.	`onError(error)`
`CHECKOUT_ERROR`	An error occurred during checkout.	`onError(error)`

If no callback is provided and a redirect_url is set, the SDK will automatically redirect after 5 seconds. If neither is provided, the modal closes after 10 seconds.

Full Integration Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Checkout Demo</title>
</head>
<body>
  <h1>Order Summary</h1>
  <p>Total: 5,000 CDF</p>
  <button id="pay-btn">Pay with Genesyspay</button>

  <script src="https://checkout.genesyspay.com/v1/sdk/js/checkout.js"></script>
  <script>
    document.getElementById('pay-btn').addEventListener('click', function () {
      var checkout = GenesyspayCheckout.create({
        pub_key: 'pk_live_xxxxxxxxxxxx',
        amount: 5000,
        currency: 'CDF',
        country: 'CD',
        tx_ref: 'order-' + Date.now(),
        description: 'Demo payment',
        redirect_url: window.location.origin + '/thank-you',
        callback_url: 'https://yourserver.com/api/webhook',
        payer_name: 'Jane Doe',
        payer_email: '[email protected]',
        payer_phone: '0707070707',
        bearer: 'customer',
        extras: { order_id: 42 },

        onSuccess: function (data) {
          alert('Payment successful! Transaction: ' + data.transaction_id);
          window.location.href = '/thank-you?tx_ref=order-' + Date.now();
        },
        onError: function (err) {
          alert('Payment failed: ' + err.message);
        },
        onClose: function () {
          console.log('User closed checkout');
        }
      });

      checkout.open();
    });
  </script>
</body>
</html>

Security Notes

The SDK uses your public key only — never expose your private/secret key in client-side code.
All payment processing happens on our secure domain over HTTPS.
Always verify the final payment status server-side using webhooks or the status API before fulfilling an order.

⚠️ Important: Do not rely solely on client-side callbacks (onSuccess) to confirm payment. Always verify server-side via your callback_url webhook.

API Documentation

JavaScript SDK