Skip to main content

​
Installation

npm install payaza-web-sdk
Alternatively, load the SDK directly via CDN — no build step required.

​
Integration

​
Option 1 — CDN (HTML)

Include the Payaza bundle script and call PayazaCheckout.setup() when the customer initiates checkout. 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <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-B0F603C4-7787-432D-B105-C7FEEDF472E1",
        connection_mode:       "Test",           // "Live" or "Test"
        checkout_amount:       Number(5000),
        currency_code:         "NGN",
        email_address:         "johndoe@example.com",
        first_name:            "John",
        last_name:             "Doe",
        phone_number:          "+2347012345678", // international format: +[country code][number]
        transaction_reference: "TXN-" + Date.now(),

        // Optional: set bank transfer expiry window (15–480 mins)
        virtual_account_configuration: {
          expires_in_minutes: 30
        },

        // Optional: attach custom metadata
        additional_details: {
          order_id: "ORD-001",
          user_id:  "USR-1273"
        }
      });

      payazaCheckout.setCallback(function(response) {
        console.log("Payment result:", response);
      });

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

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

​
Option 2 — npm / yarn (JavaScript)

import PayazaCheckout from "payaza-web-sdk";

const payazaCheckout = new PayazaCheckout({
  merchant_key:          "<your-public-api-key>",
  connection_mode:       "Live",            // "Live" or "Test"
  checkout_amount:       5000,
  currency_code:         "NGN",
  email_address:         "johndoe@example.com",
  first_name:            "John",
  last_name:             "Doe",
  phone_number:          "+2347012345678",  // international format: +[country code][number]
  transaction_reference: "TXN-" + Date.now(),

  virtual_account_configuration: {
    expires_in_minutes: 30
  },

  additional_details: {
    order_id: "ORD-001",
    user_id:  "USR-1273"
  },

  callback: function(response) {
    console.log("Payment result:", response);
  },

  onClose: function() {
    console.log("Checkout closed by user");
  }
});

payazaCheckout.showPopup();

​
Option 3 — npm / yarn (TypeScript)

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

const config: PayazaCheckoutOptionsInterface = {
  merchant_key:          "<your-public-api-key>",
  connection_mode:       "Live",
  checkout_amount:       5000,
  currency_code:         "NGN",
  email_address:         "johndoe@example.com",
  first_name:            "John",
  last_name:             "Doe",
  phone_number:          "+2347012345678",  // international format: +[country code][number]
  transaction_reference: "TXN-" + Date.now(),

  virtual_account_configuration: {
    expires_in_minutes: 30
  },

  additional_details: {
    order_id: "ORD-001",
    user_id:  "USR-1273"
  },

  callback: function(response) {
    console.log("Payment result:", response);
  },

  onClose: function() {
    console.log("Checkout closed by user");
  }
};

const checkout = new PayazaCheckout(config);
checkout.showPopup();
If setup conflicts with a function name in your codebase, import it under an alias: import { setup as PayazaSetup } from "payaza-web-sdk";

​
Phone number format

The phone_number field must be in international format — country code followed by the subscriber number, with no spaces, dashes, or + prefix.
CountryLocal formatInternational format
Nigeria 🇳🇬07012345678+2347012345678
Ghana 🇬🇭0241234567+233241234567
Kenya 🇰🇪0712345678+254712345678
South Africa 🇿🇦0821234567+27821234567
Côte d’Ivoire 🇨🇮0701234567+2250701234567
Strip the leading 0 from the local number and prepend the country code. For Nigeria: 07012345678 → +2347012345678.

​
Callback response

The callback function fires when the payment flow completes. It receives a single response object: 
{
  "type": "success",
  "status": 201,
  "data": {
    "message": "Transaction Successful",
    "payaza_reference": "P-C-20231018-1TLB7K68",
    "transaction_reference": "TXN-1697635200000",
    "transaction_fee": 100,
    "transaction_total_amount": 5100,
    "currency": {
      "name": "Naira",
      "code": "NGN",
      "unicode": "₦",
      "html_value": "&#8358;"
    },
    "customer": {
      "customer_id": "HCC4ZX96W",
      "email_address": "johndoe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "mobile_number": "+2347012345678"
    }
  }
}
Always verify the payment server-side using the transaction_reference before fulfilling an order. The callback fires on the client and can be intercepted. Use the Transaction Status Query API or listen for a webhook to confirm the final state.

​
Errors

Ensure all required parameters are present and correctly formatted before calling showPopup().

​
Invalid merchant key

{
  "type": "error",
  "status": 401,
  "data": {
    "message": "Sorry merchant key is not valid"
  }
}

​
Validation error

{
  "type": "error",
  "status": 400,
  "data": {
    "message": "Error during validation",
    "errors": [
      {
        "field": "merchant_key",
        "errors": ["'merchant_key' is required"]
      },
      {
        "field": "checkout_amount",
        "errors": ["'checkout_amount' must be numeric"]
      },
      {
        "field": "first_name",
        "errors": ["'first_name' cannot be blank"]
      },
      {
        "field": "email_address",
        "errors": [
          "'email_address' cannot be blank",
          "'email_address' must be a valid email address"
        ]
      }
    ]
  }
}

​
Environment mismatch

{
  "type": "error",
  "status": 401,
  "data": {
    "message": "Business Profile Credentials does not match connection mode selected"
  }
}

​
Parameters

​
Required

​
merchant_key
string
required
Your public API key from the Payaza dashboard. Do not Base64-encode this — pass the raw key directly.
​
connection_mode
string
required
Environment for the transaction. Accepts "Live" or "Test". Must match the environment of your merchant_key.
​
checkout_amount
number
required
Amount to charge the customer. Pass as a number — e.g. 5000. Do not pass as a string.
​
currency_code
string
required
ISO currency code — e.g. "NGN", "GHS", "USD".
​
email_address
string
required
The customer’s email address. Used for payment receipts and customer identification.
​
first_name
string
required
The customer’s first name.
​
last_name
string
required
The customer’s last name.
​
phone_number
string
required
The customer’s phone number in international format — country code followed by the number, no spaces or dashes. Example: "+2347012345678" for Nigeria. See the phone number format table above.
​
transaction_reference
string
required
A unique identifier you generate for each transaction. Must be unique per payment attempt — reusing a reference will cause an error.

​
Optional

​
country_code
string
Required only for CIV and BEN collections. Pass the ISO country code — e.g. "CIV" or "BEN". Not needed for NGN, GHS, or other standard currencies.
​
biller_name
string
Overrides the business name shown on the checkout page. Defaults to your registered Payaza business name if omitted.
​
virtual_account_configuration
object
Controls the bank transfer option in the checkout modal. Set expires_in_minutes to define how long the virtual account stays active. Min: 15, max: 480. Defaults to 30 if omitted.
{
  "expires_in_minutes": 30
}
​
additional_details
object
Custom metadata attached to the transaction — e.g. order ID, user ID, ticket reference. Returned in the callback response. Must be a valid JSON object.
{
  "order_id": "ORD-001",
  "user_id": "USR-1273"
}
​
callback
function
Called when the payment flow completes (success or failure). Receives the transaction outcome object. See Callback response above.
​
onClose
function
Called when the user closes the checkout modal before completing payment.