Web Checkout Guide - Payaza Documentation

Overview

The Payaza Web Checkout SDK gives you a hosted, secure payment modal that handles card charges, virtual account bank transfers, and mobile money collections — without you building the payment UI yourself. Add it to any website in minutes.

Via CDN (HTML)

Include the Payaza bundle script in your HTML and call PayazaCheckout.setup().

Via npm / yarn

Install the payaza-web-sdk package and import it into your JavaScript or TypeScript project.

Prerequisites

Before integrating, make sure you have:

An active Payaza business account — sign up here
Your Public API Key from the dashboard — see the Authentication guide
A Collection Webhook URL configured on the dashboard — see the Webhooks guide

Your raw API key goes directly into the SDK as merchant_key. You do not need to Base64-encode it for the Checkout SDK — Base64 encoding is only required for direct REST API calls.

Integration

Option 1 — HTML (CDN)

Include the Payaza bundle script in your <head> and call PayazaCheckout.setup() when the user initiates checkout.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Checkout</title>
  <script defer src="https://checkout-v2.payaza.africa/js/v1/bundle.js"></script>
  <script defer>
    function handleCheckout() {
      const payazaCheckout = PayazaCheckout.setup({
        merchant_key: "PZ78-PKTEST-YOUR-KEY-HERE",
        connection_mode: "Test", // "Live" or "Test"
        checkout_amount: 5000,
        currency_code: "NGN",
        email_address: "customer@example.com",
        first_name: "John",
        last_name: "Doe",
        phone_number: "07012345678",
        transaction_reference: "TXN-" + Date.now(),
        virtual_account_configuration: {
          expires_in_minutes: 15
        },
        additional_details: {
          order_id: "ORD-001"
        }
      });

      payazaCheckout.setCallback(function(response) {
        console.log("Payment result:", response);
        // Handle success or failure here
      });

      payazaCheckout.setOnClose(function() {
        console.log("Checkout modal closed");
      });

      payazaCheckout.showPopup();
    }
  </script>
</head>
<body>
  <button onclick="handleCheckout()">Pay Now</button>
</body>
</html>

Option 2 — npm / yarn

Install the package:

npm install payaza-web-sdk
# or
yarn add payaza-web-sdk

JavaScript:

import PayazaCheckout from "payaza-web-sdk";

const payazaCheckout = new PayazaCheckout({
  merchant_key: "PZ78-PKTEST-YOUR-KEY-HERE",
  connection_mode: "Live", // "Live" or "Test"
  checkout_amount: 5000,
  currency_code: "NGN",
  email_address: "customer@example.com",
  first_name: "John",
  last_name: "Doe",
  phone_number: "07012345678",
  transaction_reference: "TXN-" + Date.now(),
  virtual_account_configuration: {
    expires_in_minutes: 15
  },
  additional_details: {
    order_id: "ORD-001"
  },
  callback: function(response) {
    console.log("Payment result:", response);
  },
  onClose: function() {
    console.log("Checkout closed");
  }
});

payazaCheckout.showPopup();

TypeScript:

import PayazaCheckout from "payaza-web-sdk";
import { PayazaCheckoutOptionsInterface } from "payaza-web-sdk/lib/PayazaCheckoutDataInterface";

const config: PayazaCheckoutOptionsInterface = {
  merchant_key: "PZ78-PKTEST-YOUR-KEY-HERE",
  connection_mode: "Live",
  checkout_amount: 5000,
  currency_code: "NGN",
  email_address: "customer@example.com",
  first_name: "John",
  last_name: "Doe",
  phone_number: "07012345678",
  transaction_reference: "TXN-" + Date.now(),
  virtual_account_configuration: {
    expires_in_minutes: 15
  },
  callback: function(response) {
    console.log("Payment result:", response);
  },
  onClose: function() {
    console.log("Checkout closed");
  }
};

const checkout = new PayazaCheckout(config);
checkout.showPopup();

Handling the callback response

The callback function fires when the payment flow completes. It receives a response object with the outcome:

{
  "type": "success",
  "status": 201,
  "data": {
    "message": "Transaction Successful",
    "payaza_reference": "P-C-20231018-1TLB7K68",
    "transaction_reference": "TXN-1234567890",
    "transaction_fee": 100,
    "transaction_total_amount": 5100,
    "currency": {
      "name": "Naira",
      "code": "NGN",
      "unicode": "₦",
      "html_value": "&#8358;"
    },
    "customer": {
      "customer_id": "HCC4ZX96W",
      "email_address": "customer@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "mobile_number": "07012345678"
    }
  }
}

Always verify the payment server-side using the transaction_reference before fulfilling an order. The callback fires on the client — it can be intercepted. Use the Transaction Status Query API or listen for a webhook to confirm the final state.

SDK parameters

Parameter	Type	Required	Description
`merchant_key`	`string`	Yes	Your Public API key (raw, not Base64-encoded)
`connection_mode`	`string`	Yes	`"Live"` or `"Test"` — must match your key’s environment
`checkout_amount`	`number`	Yes	Amount to charge the customer
`currency_code`	`string`	Yes	ISO currency code — e.g. `"NGN"`, `"GHS"`
`email_address`	`string`	Yes	Customer’s email address
`first_name`	`string`	Yes	Customer’s first name
`last_name`	`string`	Yes	Customer’s last name
`phone_number`	`string`	Yes	Customer’s phone number
`transaction_reference`	`string`	Yes	Unique reference for this transaction — must be unique per payment
`country_code`	`string`	No	Required for CIV/BEN collections — e.g. `"BEN"`, `"CIV"`
`biller_name`	`string`	No	Overrides the name shown on the checkout page
`virtual_account_configuration`	`object`	No	Set `expires_in_minutes` to control the bank transfer account expiry (default 30 min)
`additional_details`	`object`	No	Custom metadata attached to the transaction (e.g. order ID, user ID)
`callback`	`function`	No	Called when the payment completes (success or failure)
`onClose`	`function`	No	Called when the user closes the checkout modal

SDK errors

Error	Cause	Fix
`"Sorry merchant key is not valid"`	The `merchant_key` is incorrect or from the wrong environment	Copy the key from your dashboard and check `connection_mode` matches
`"Business Profile Credentials does not match connection mode selected"`	Key is a test key but `connection_mode: "Live"` (or vice versa)	Match `connection_mode` to the key environment
`"'merchant_key' is required"`	`merchant_key` was not passed	Pass the `merchant_key` parameter
`"'checkout_amount' must be numeric"`	Amount was passed as a string	Pass `checkout_amount` as a `Number`, e.g. `Number(5000)`
`"'email_address' must be a valid email address"`	Invalid or missing email	Pass a valid email in the `email_address` field

Testing

Use Test Mode test cards to simulate different payment outcomes before going live. Set connection_mode: "Test" and use your test API key.

Payments made in Test Mode are not processed or settled. Switch connection_mode to "Live" and use your live API key only when you are ready to accept real payments.

What’s next

Webhooks

Set up server-side event notifications to confirm payments and update order state.

Test Cards

Simulate card approvals, declines, and 3DS flows during development.

Card Collections API

Build a fully custom card checkout without the hosted SDK.

Virtual Accounts

Collect payments via bank transfer using dynamic or reserved account numbers.

​Overview

Via CDN (HTML)

Via npm / yarn

​Prerequisites

​Integration

​Option 1 — HTML (CDN)

​Option 2 — npm / yarn

​Handling the callback response

​SDK parameters

​SDK errors

​Testing

​What’s next

Webhooks

Test Cards

Card Collections API

Virtual Accounts

Overview

Prerequisites

Integration

Option 1 — HTML (CDN)

Option 2 — npm / yarn

Handling the callback response

SDK parameters

SDK errors

Testing

What’s next