> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payaza.africa/llms.txt
> Use this file to discover all available pages before exploring further.
# Web Checkout Guide
> Integrate the Payaza Checkout SDK into your website to accept card, bank transfer, and mobile money payments with a pre-built, hosted checkout flow.
## 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.
Include the Payaza bundle script in your HTML and call `PayazaCheckout.setup()`.
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](https://business.payaza.africa/signup)
* Your **Public API Key** from the dashboard — see the [Authentication guide](/guides/authentication)
* A **Collection Webhook URL** configured on the dashboard — see the [Webhooks guide](/guides/webhooks)
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 `` and call `PayazaCheckout.setup()` when the user initiates checkout.
```html theme={null}
Checkout
```
***
### Option 2 — npm / yarn
**Install the package:**
```bash theme={null}
npm install payaza-web-sdk
# or
yarn add payaza-web-sdk
```
**JavaScript:**
```javascript theme={null}
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:**
```typescript theme={null}
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:
```json theme={null}
{
"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": "₦"
},
"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](/api-reference/introduction) or listen for a [webhook](/guides/webhooks) 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](/guides/testcards) 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
Set up server-side event notifications to confirm payments and update order state.
Simulate card approvals, declines, and 3DS flows during development.
Build a fully custom card checkout without the hosted SDK.
Collect payments via bank transfer using dynamic or reserved account numbers.