Checkout SDK

The PayOnUs Checkout SDK is a drop-in JavaScript library that renders a payment modal on your website. It supports Card, Bank Transfer, PalmPay, and Opay payments. No build tools or external dependencies required — include the script and call checkout().

Installation

<script src="https://payonus.com/checkout-v2.min.js"></script>

Single file, ~104 KB minified. All styles, HTML templates, validation, and encryption are bundled internally. The only external dependency (JSEncrypt for card encryption) is loaded automatically from CDN when a card payment is initiated.

Quick Start

<script src="https://payonus.com/checkout-v2.min.js"></script>
<script>
  OnUsCheckout.init();

  document.getElementById('pay-btn').addEventListener('click', function () {
    OnUsCheckout.checkout({
      businessId: "your-business-id",
      amount: 5000,
      currency: "NGN",
      customerEmail: "customer@example.com",
      customerName: "John Doe",
      customerPhone: "+2347011221122",
      merchantCheckoutReference: "ORDER-" + Date.now(),
      countryCode: "NG",
      notificationUrl: "https://yourserver.com/webhook",
      redirectUrl: window.location.origin,
      environment: "production",
      paymentMethods: ["card", "bank", "palmpay", "opay"],

      onSuccess: function (result) {
        console.log("Payment successful:", result);
      },
      onError: function (error) {
        console.log("Payment failed:", error);
      },
      onClose: function () {
        console.log("Checkout closed");
      }
    });
  });
</script>

The SDK renders a payment modal, handles the entire payment flow, and calls your callbacks when done.

Initialization

OnUsCheckout.init();

Call this once before triggering any checkout. It injects the SDK's styles and HTML template into the page.

Setting Environment

OnUsCheckout.setEnvironment('test');       // Sandbox
OnUsCheckout.setEnvironment('production'); // Live

Environment	API Base URL
test	`https://core-sandbox.payonus.com`
production	`https://core.payonus.com`

You can also pass environment directly in the checkout options.

Custom Public Keys (Optional)

OnUsCheckout.setPublicKey('test', 'your-test-public-key');
OnUsCheckout.setPublicKey('production', 'your-prod-public-key');

Used for client-side RSA encryption of card data. Default keys are built into the SDK.

Checkout Options

OnUsCheckout.checkout(options);

Required Fields

Field	Type	Required	Description
businessId	string	Yes	Your PayOnUs business ID
amount	number	Yes	Payment amount
customerEmail	string	Yes	Customer's email address
merchantCheckoutReference	string	Yes	Your unique reference for this order

Optional Fields

Field	Type	Required	Default	Description
currency	string	No	`"NGN"`	`"NGN"` or `"USD"`
customerName	string	No	`""`	Customer's full name
customerPhone	string	No	`"+2347000000000"`	Customer's phone number
countryCode	string	No	—	Alpha-2 country code e.g. `"NG"`
notificationUrl	string	No	—	Webhook URL for payment notifications
redirectUrl	string	No	`window.location.origin`	Where to redirect after payment
environment	string	No	`"production"`	`"test"` or `"production"`
paymentMethods	array	No	all methods	Subset of `["card", "bank", "palmpay", "opay"]`

Callbacks

Callback	Description
onSuccess	Called when payment completes successfully
onError	Called when payment fails or encounters an error
onClose	Called when customer closes the checkout modal

Payment Methods

Card Payment

Supports Visa, Mastercard, and Verve. The SDK handles card type detection, input formatting, client-side RSA encryption, and multi-step authentication (PIN, OTP, Card Enrollment, 3D Secure).

Flow:

Customer fills card form (number, CVV, expiry, email)
Card data is encrypted client-side using RSA-2048
SDK initiates payment via POST /api/v1/card-payments/checkout
If additional authentication is required (PIN/OTP/3DS), the SDK shows the appropriate form
SDK completes payment via POST /api/v1/card-payments/complete-payment/checkout
onSuccess or onError callback is fired

Bank Transfer

Generates a dynamic virtual account for the customer to transfer to.

Flow:

SDK creates a dynamic account via POST /api/v1/virtual-accounts/dynamic/checkout
Account number, bank name, and account name are displayed with copy buttons
Customer transfers funds via their bank
Customer clicks "Confirm Transfer"
SDK verifies payment status
onSuccess or onError callback is fired

PalmPay

Redirects customer to PalmPay to complete payment.

Flow:

SDK requests a PalmPay payment link via POST /api/v1/virtual-accounts/dynamic/checkout with walletType: PALMPAY
PalmPay completion URL opens in a new window
Progress modal is shown while customer completes payment in PalmPay
Customer clicks "Check Status" to verify
onSuccess or onError callback is fired

Opay

Same flow as PalmPay but redirects to Opay.

Flow:

SDK requests an Opay payment link via POST /api/v1/virtual-accounts/dynamic/checkout with walletType: OPAY
Opay completion URL opens in a new window
Progress modal is shown while customer completes payment in Opay
Customer clicks "Check Status" to verify
onSuccess or onError callback is fired

Callback Responses

onSuccess

{
  "reference": "your-merchant-checkout-reference",
  "onusReference": "onus-transaction-reference",
  "amount": 5000,
  "method": "card",
  "status": "successful"
}

The method field will be one of: card, bank_transfer, palmpay_transfer, opay_transfer.

onError

{
  "error": "Error message describing what went wrong",
  "code": "NETWORK_ERROR"
}

onClose

No arguments. Fired when the customer closes the modal without completing payment.

Supported Currencies

Currency	Symbol
NGN	₦
USD	$

Example Integration

<!DOCTYPE html>
<html>
<head>
    <title>My Store</title>
</head>
<body>
    <button id="pay-btn">Pay NGN 5,000</button>

    <script src="https://payonus.com/checkout-v2.min.js"></script>
    <script>
        OnUsCheckout.init();
        OnUsCheckout.setEnvironment('test');

        document.getElementById('pay-btn').addEventListener('click', function () {
            OnUsCheckout.checkout({
                businessId: "your-business-id",
                amount: 5000,
                currency: "NGN",
                customerEmail: "customer@example.com",
                customerName: "John Doe",
                customerPhone: "+2347011221122",
                merchantCheckoutReference: "ORDER-" + Date.now(),
                countryCode: "NG",
                notificationUrl: "https://yourserver.com/webhook",
                paymentMethods: ["card", "bank"],

                onSuccess: function (result) {
                    alert("Payment successful! Reference: " + result.onusReference);
                },
                onError: function (error) {
                    alert("Payment failed: " + error.error);
                },
                onClose: function () {
                    console.log("Checkout closed");
                }
            });
        });
    </script>
</body>
</html>

Notes

Call OnUsCheckout.init() once before any checkout call.
Each checkout call requires a unique merchantCheckoutReference.
You will receive a webhook notification when a payment is completed. See Webhook Notifications for details.
You can verify the status of a payment using the Verify Single Payment endpoint with the onusReference returned in the onSuccess callback.
Use paymentMethods to control which payment options are shown to the customer.
For sandbox testing, set environment to "test". See Card Payments for test card numbers.