# Initiate Payment
Source: https://docs.payaza.africa/api-reference/apple-pay-and-google-pay/initiate-payment
/openapi.json post /merchant-collection/mobile_payment/initiate
This endpoint is used to initiate an Apple Pay or Google Pay collection.
**Notes:**
- Please be advised that access to this API is available upon request. To initiate this process, kindly send an email to **support@payaza.africa**. You will be granted access once our team reviews and approves your request.
- Ensure that the Check Transaction Status API using the merchant reference is used for your transaction status checks which can be found [here](/api-reference/check-transaction-statusmerchant-reference/check-transaction-statusmerchant-reference).
# Authorize Transaction
Source: https://docs.payaza.africa/api-reference/auth-capture-void/authorize-transaction
/openapi.json post /card/auth_capture/authorize
This endpoint authorizes a transaction and holds funds for a specified period. This endpoint handles payout requests.
> **Record Creation:**
>
> Authorization record is created with **PENDING** status before MPGS call, then updated to **AUTHORIZED** on success or **FAILED** on error.
>
# Capture Transaction
Source: https://docs.payaza.africa/api-reference/auth-capture-void/capture-transaction
/openapi.json post /card/auth_capture/capture
This endpoint captures a previously authorized transaction.
# Get All Authorizations
Source: https://docs.payaza.africa/api-reference/auth-capture-void/get-all-authorizations
/openapi.json get /card/auth_capture/authorize?status=AUTHORIZED&page={page}&size={size}&from_date={from_date}&to_date={to_date}
The merchant uses this endpoint to fetch refund transaction history. The data output can be filtered using a date range and/or status..
# Get Single Authorization
Source: https://docs.payaza.africa/api-reference/auth-capture-void/get-single-authorization
/openapi.json get /card/auth_capture/authorize/{authorization_reference}
This endpoint retrieves details of a single authorization by its authorization_reference.
> **Notes:**
>
> 1. **authorization_reference:**: Must exist and belong to the requesting merchant.
> 2. **Merchant Ownership:** Strictly enforced - only the business that created the authorization can retrieve it. Attempting to access another business’s authorization returns 403 Forbidden.
> 3. **Authentication:** Valid Authorization header required (same format as authorize endpoint).
> 4. **Security:** The system verifies business ownership by comparing the authenticated business.
# Void Transaction
Source: https://docs.payaza.africa/api-reference/auth-capture-void/void-transaction
/openapi.json post /card/auth_capture/void
This endpoint voids a previously authorized transaction. This request can only be done on transactions that are fully authorized and have not been captured
> **Notes:**
>
> 1. **Partially captured authorizations cannot be voided**: If any amount has been captured, void is not allowed. The response will indicate the remaining capturable amount..
> 2. **Fully captured authorizations cannot be voided::** Once a transaction is fully captured (status becomes CAPTURED), it cannot be voided. You must use the refund API instead.
> 3. **Authentication:** Valid Authorization header required (same format as authorize endpoint).
> 4. **Only fully authorized (uncaptured) transactions can be voided:** Void is only allowed for authorizations that have never been captured.
# Fetch All Branches
Source: https://docs.payaza.africa/api-reference/branches/fetch-all-branches
/openapi.json get /branches/api/v1/merchant-branches
This fetches all branches that have been created by a Payaza account.
# Card Charge
Source: https://docs.payaza.africa/api-reference/card-collection/card-charge
/openapi.json post /card/card_charge/
This endpoint is used to initiate Card payments for merchants that use our platform. This document has various Request bodies and HTML text that are necessary for different integration purposes. See the full [Cards guide](/guides/card-collection) for a step-by-step walkthrough.
**Note:**
- The Card Acquirer Response Codes with descriptions can be found here
- Please be advised that card collections to countries other than Nigeria are exclusively available upon request. To initiate this process, kindly send an email to support@payaza.africa. You will be granted access once our team reviews and approves your request.
# Check Refund Status
Source: https://docs.payaza.africa/api-reference/card-collection/check-refund-status
/openapi.json post /card/card_charge/refund_status
This endpoint is used to fetch the status of a refunded card payment (transaction).
# Check Transaction Status
Source: https://docs.payaza.africa/api-reference/card-collection/check-transaction-status
/openapi.json post /card/card_charge/transaction_status
This endpoint gets the transaction status corresponding to the provided transaction reference for a card transaction.
# Check Transaction Status(Merchant Reference)
Source: https://docs.payaza.africa/api-reference/check-transaction-statusmerchant-reference/check-transaction-statusmerchant-reference
/openapi.json get /merchant-collection/transfer_notification_controller/merchant/transaction-query?merchant_reference={merchantReference}
This endpoint is used to check the transaction status of a transaction using the Merchant Reference value placed in the checkout or payment page request.
| Status | Meaning |
| :--- | :--- |
| Initialized | The transaction is in progress |
| Completed | The transaction is successful |
| Failed | The transaction has failed |
# Flutter
Source: https://docs.payaza.africa/api-reference/libraries/flutter
Payaza’s Flutter SDK makes it easy for you to start accepting payments from your customers when they visit your applications. The checkout SDK can be integrated in very easy steps, making it the easiest way to start accepting payments.
## Getting started
To start collecting payment with Payaza install **payaza** widget by adding as a in **pubspec.yaml** dependency
```
dependencies:
payaza: ^1.0.0
```
### Usage
Initialize SDK anywhere before use
```
//...
Payaza.init('');
runApp(const MyApp());
//...
```
```
// ...
import 'package:payaza/payaza.dart';
// ...
void handleSuccess(PayazaSuccessResponse response) async {
await showAlert(
message: response.data.payazaReference ?? '',
title: 'Payment Successful');
if (context.mounted) {
Navigator.of(context).pop();
}
}
void handleError(PayazaErrorResponse response) async {
await showAlert(message: response.data.message, title: 'Error');
if (context.mounted) {
Navigator.of(context).pop();
}
}
void handleClose() {
print('Payaza widget was closed');
}
void onSubmit() {
Payaza.createTransaction(
context,
config: PayazaConfig(
amount: 110,
connectionMode: PayazaConnectionMode.LIVE_CONNECTION_MODE,
email: "example@example.com",
firstName: "",
lastName: "",
phoneNumber: "<+12345678900>",
transactionReference: "transaction_reference",
currencyCode: ,
),
onSuccess: handleSuccess,
onError: handleError,
onClose: handleClose,
);
}
```
### Arguments
| Parameter | Description | Format |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| email | The email address of the customer. | string |
| firstName | The first name of the customer. | string |
| lastName | The last name of the customer. | string |
| phone\_number | The phone number of the customer. It must be international standard i.e. +2348012345678 | string |
| transactionReference | This is the transaction reference that you generated for the transaction. This unique and no 2 transactions can have the same reference.. | string |
| merchantKey | This is your public API Key. | string |
| connectionMode | Mode of session (LIVE\_CONNECTION\_MODE or TEST\_CONNECTION\_MODE). | string |
| amount | The amount the customer is expected to pay. | double |
| currencyCode | It refers to the code of the currency.(NGN, USD etc.). | string |
# IOS Swift
Source: https://docs.payaza.africa/api-reference/libraries/iosswift
IOS SDK aids in processing payment through the following channels: Cards, Bank and Virtual Transfer..
### Example
To run the example project, clone the repo, and run pod install from the Example directory first.
### Requirements
Payaza SDK is compatible with iOS apps running on iOS 11.0 and above. It requires Xcode 10.0+ to build the source..
### Example
PayAzaSDK is available through [Cocoapods](https://cocoapods.com). To install it, simply add the following line to your Podfile:
```FOR FOR PODFILE theme={null}
source 'https://github.com/78-Financials/Specs.git'
source 'https://github.com/CocoaPods/Specs.git'
pod 'PayAzaSDK'
```
### In your terminal, run
```
pod update && pod install
```
### Usage
There are three steps you would have to complete to set up the SDK and perform transactionStatus
1. Install the SDK as a dependency.
2. Configure the SDK with Merchant Information.
3. Initiate Payment with customer details.
```Request Request Sample theme={null}
import PayazaPod
class ViewController: UIViewController, PayazaCallbackMethods {
private var transactionAmount: Int64?
@objc func showExample(){
let baseUrl = "https://your-base-url"
let manager = PayazaManager()
transactionAmount = 100
manager.initialize(delegateController: self, viewControler: self)
manager.PayAzaConfig(merchantKey: "Your Merchant Key Here", merchantName: "Test Merchant", currency: "NGN", firstname: "Firstname",
lastname: "Lastname", email: "emailAdreess", phone: "Phone", transactionRef: "transactionReference",
amount: transactionAmount!, isLive: true, baseUrl: baseUrl) // Set isLive to false during testing and set to true during production
manager.payNow()
}
func onPaymentComplete(response: TransactionResponse) {
print("Successful with (response.reference ?? "Failed to return data")")
}
func onPaymentCancelled(errorMessage: String) {
print( errorMessage)
}
}
```
### Arguments
| Parameter | Description | Format |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| baseUrl | The URL of the payment service | string |
| email | The email address of the customer. | string |
| firstName | The first name of the customer. | string |
| lastName | The last name of the customer. | string |
| phone | The phone number of the customer. It must be international standard i.e. +2348012345678 | string |
| transactionref | This is the transaction reference that you generated for the transaction. This unique and no 2 transactions can have the same reference.. | string |
| merchantKey | This is your public API Key. | string |
| isLive | Mode of session (If False, it is in test mode, if True, It is in live mode). | boolean |
| transactionAmount | The amount that the customer would pay. | amount |
| currency | It refers to the code of the currency.(NGN, USD etc.). | string |
# Payment Page
Source: https://docs.payaza.africa/api-reference/libraries/paymentpage
Welcome to the Payment Page documentation. This guide will help you integrate our payment gateway and implement a secure and seamless checkout experience on your website.
## Introduction
Payment Page provides a secure and PCI-compliant solution for processing online payments. It allows your customers to complete their transactions on a secure payment page hosted by our payment gateway, reducing your PCI scope and ensuring a seamless checkout experience.
## Getting Started
### Retrieving your API Keys.
To use our Payment Page, you will need an API key. Your API keys are available on your dashboard. Follow the steps below to access them:
1. Login to your **Payaza** dashboard
2. Click on the **Settings** option which is located on the left side-bar of the dashboard
3. Click the **Developers** option from the dropdown menu
4. Click on the **Generate Keys** Button to generate your API keys which can also be copied.
### Integration Steps.
1. Payment Page Checkout URL - [https://payment.payaza.africa/](https://payment.payaza.africa/) Redirects the customer to the Payment Page Checkout page, appending the following parameters to the URL provided above.
2. On the Payment Page Checkout page, the customer will enter their payment details and complete the transaction.
```
https://payment.payaza.africa/?merchant_key=PZ78-PKLIVE-8D51A540-4A36-4901-A314-43C9AB859068&connection_mode=live&checkout_amount=500¤cy_code=NGN&country_code=NGA&email_address=johndoe@gmail.com&first_name=John&last_name=Doe&phone_number=23480123456&transaction_reference=testpayrment&redirect_url=https://google.com
```
### HTML Code Block
```md theme={null}
Sample Webpage
Sample Webpage
```
### Arguments
| Parameter | Description | Format |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | ------ |
| merchant\_key | Your public API key. | string |
| connection\_mode | Connection mode. (Live or Test). | string |
| checkout\_amount | The amount to charge the customer. | double |
| currency\_code | The currency to charge in. | string |
| email\_address | The email address of the customer. | string |
| first\_name | The first name of the customer. | string |
| last\_name | The last name of the customer. | string |
| phone\_number | The phone number of the customer. | string |
| transaction\_reference | The unique identifier given to a particular transaction by the merchant. | string |
| additional\_details | The custom data to your payload (should be encoded). | JSON |
| redirect\_url | The URL the customer is redirected to (should be encoded). This must be the last parameter in the request if included | string |
# React Native
Source: https://docs.payaza.africa/api-reference/libraries/reactnative
Payaza React Native Library.
## Installation
```
npm install react-native-payaza
```
```
yarn add react-native-payaza
```
### Installing Dependecies
Install React Native Webview
```
npm install react-native-webview
```
For Bear React Native flow
```
npm install --save @react-native-clipboard/clipboard
```
### Link Native Dependecies
From react-native 0.60 autolinking will take care of the link step but don't forget to run pod install
React Native modules that include native Objective-C, Swift, Java, or Kotlin code have to be "linked" so that the compiler knows to include them in the app.
```
react-native link react-native-webview
```
## Usage
Import the package
```
import Payaza, {
type IPayaza,
type PayazaErrorResponse,
type PayazaSuccessResponse,
PayazaConnectionMode,
} from 'react-native-payaza'
// ...
const payaza = React.useRef(null);
// ...
const payNow = () => {
payaza.current?.createTransaction({
amount: Number(110),
connectionMode: PayazaConnectionMode.LIVE_CONNECTION_MODE,
email: "example@example.com",
firstName: "",
lastName: "",
phoneNumber: "<+12345678900>",
currencyCode: 'NGN',
transactionReference: "transaction_reference",
});
}
const handleError = (response: PayazaErrorResponse) => {
Alert.alert(response.data.message, 'Error Occurred');
};
const handleSuccess = (response: PayazaSuccessResponse) => {
Alert.alert(
response.data.message,
`Transaction reference {$response.data.payaza_reference}`
);
};
// ...
return (
Pay Now
)
```
### Arguments
| Parameter | Description | Format |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| email | The email address of the customer. | string |
| firstName | The first name of the customer. | string |
| lastName | The last name of the customer. | string |
| phone\_number | The phone number of the customer. It must be international standard i.e. +2348012345678 | string |
| transactionReference | This is the transaction reference that you generated for the transaction. This unique and no 2 transactions can have the same reference.. | string |
| merchantKey | This is your public API Key. | string |
| connectionMode | Mode of session (LIVE\_CONNECTION\_MODE or TEST\_CONNECTION\_MODE). | string |
| amount | The amount the customer is expected to pay. | amount |
| currencyCode | It refers to the code of the currency.(NGN, USD etc.). | string |
# Web SDK
Source: https://docs.payaza.africa/api-reference/libraries/websdk
Integrate the Payaza Checkout SDK into any website to accept card, bank transfer, and mobile money payments with a prebuilt, hosted payment modal.
## Installation
```bash npm theme={null}
npm install payaza-web-sdk
```
```bash yarn theme={null}
yarn add 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.
```html theme={null}
Checkout
```
***
### Option 2 — npm / yarn (JavaScript)
```javascript theme={null}
import PayazaCheckout from "payaza-web-sdk";
const payazaCheckout = new PayazaCheckout({
merchant_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,
},
// Optional: Add Your subscription Plan ID here
subscription: {
plan_id: "PLN_D1D8BFF",
},
// Optional: attach split account
split_accounts: [
{
code: "SSA_C0900E891783950401871",
},
],
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)
```typescript theme={null}
import PayazaCheckout from "payaza-web-sdk";
import { PayazaCheckoutOptionsInterface } from "payaza-web-sdk/lib/PayazaCheckoutDataInterface";
const config: PayazaCheckoutOptionsInterface = {
merchant_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,
},
// Optional: Add Your subscription Plan ID here
subscription: {
plan_id: "PLN_D1D8BFF",
},
additional_details: {
order_id: "ORD-001",
user_id: "USR-1273",
},
// Optional: attach split account
"split_accounts": [
{
"code": "SSA_C0900E891783950401871”,
“ratio”: 1
},
{
"code": "SSA_39B5E6E91783951863120",
“ratio”: 9
}
],
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.
| Country | Local format | International 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:
```json theme={null}
{
"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": "₦"
},
"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](/api-reference/introduction) or listen
for a [webhook](/guides/webhooks) to confirm the final state.
***
## Errors
Ensure all required parameters are present and correctly formatted before calling `showPopup()`.
### Invalid merchant key
```json theme={null}
{
"type": "error",
"status": 401,
"data": {
"message": "Sorry merchant key is not valid"
}
}
```
### Validation error
```json theme={null}
{
"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
```json theme={null}
{
"type": "error",
"status": 401,
"data": {
"message": "Business Profile Credentials does not match connection mode selected"
}
}
```
***
## Parameters
### Required
Your public API key from the Payaza dashboard. Do **not** Base64-encode this —
pass the raw key directly.
Environment for the transaction. Accepts `"Live"` or `"Test"`. Must match the
environment of your `merchant_key`.
Amount to charge the customer. Pass as a number — e.g. `5000`. Do not pass as
a string.
ISO currency code — e.g. `"NGN"`, `"GHS"`, `"USD"`.
The customer's email address. Used for payment receipts and customer
identification.
The customer's first name.
The customer's last name.
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](#phone-number-format) above.
A unique identifier you generate for each transaction. Must be unique per
payment attempt — reusing a reference will cause an error.
***
### Optional
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.
Overrides the business name shown on the checkout page. Defaults to your
registered Payaza business name if omitted.
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.
```json theme={null}
{
"expires_in_minutes": 30
}
```
Set `plan_id` to the planCode value that was created using the Create Plan API or from your Payaza Dashboard which acts as a unique identifier for your subscription plan.
```json theme={null}
{
"plan_id": PLN_D1D8BFF
}
```
An array containing the split account values and corresponding ratios.
### Field Parameters
* **`code`** (string): Set this to the unique split account identifier value that was generated using the **Create Split Account API**.
* **`ratio`** (integer): Defines the relative weighted portion used to calculate how the transaction remainder is divided between the split accounts.
### Ratio Rules
The calculation matches integers directly to decimal percentage scales where `1` represents 10%, `2` represents 20%, `3` represents 30%, and `4` represents 40% allocations.
> **Critical Rule:** When assigning multiple split account elements inside this configuration array, the cumulative sum of all `ratio` values **must equal exactly 10 in total** (representing 100%).
```json Example Payload theme={null}
"split_accounts": [
{
"code": "SSA_C0900E891783950401871",
"ratio": 1
},
{
"code": "SSA_39B5E6E91783951863120",
"ratio": 9
}
]
```
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.
```json theme={null}
{
"order_id": "ORD-001",
"user_id": "USR-1273"
}
```
Called when the payment flow completes (success or failure). Receives the
transaction outcome object. See [Callback response](#callback-response) above.
Called when the user closes the checkout modal before completing payment.
# WordPress
Source: https://docs.payaza.africa/api-reference/libraries/wordpress
Effortlessly start accepting card payments, bank transfers, and other payment methods with the official Payaza Plugin for WooCommerce. Easily integrate Payaza into your store and give your customers a smooth, secure payment experience.
Before you begin, ensure you have the following: - A **Payaza merchant
account** — [Create an account here](https://business.payaza.africa/signup). -
An active **WordPress** site with the **WooCommerce** plugin installed.
## Configuration
Please adhere to the steps outlined below to configure your Payaza plugin:
Access your store's WordPress Admin dashboard and navigate to the 'Plugins' section in the left-hand side menu.
Click on the dropdown menu and select the **'Add new'** button.
Search for Payaza and install the plugin as directed.
After installation, locate the 'Installed Plugins' section in the left-hand side menu under Plugins. Activate the Payaza plugin that was recently installed.
Further customization can be done by clicking on Woocommerce > Settings in the left menu.
You can retrieve your API keys from your Payaza merchant dashboard under **Settings > API Keys & Webhooks**.
Navigate to payments, and click on 'Manage' to configure your settings as required.
# Momo, XOF and ZAR Process Collection
Source: https://docs.payaza.africa/api-reference/momo-and-zar-collections/momo-xof-and-zar-process-collection
/openapi.json post /subsidiary/collections/v1/process-collection
This endpoint initiates mobile money collection for various currencies such as KES, GHS, UGX, TZS, LRD, ZAR, XOF, CDF and XAF. The Momo collections guide can be found [here](/guides/momo-collections)
**Notes:**
- Payaza MOMO collection codes can be accessed here.
- Please be advised that collections to countries other than Nigeria are exclusively available upon request. To initiate this process, kindly send an email to [support@payaza.africa](mailto:support@payaza.africa). You will be granted access once our team reviews and approves your request.
- For XOF testing purposes, please use either **225000476807** for the No OTP Required option or **2251114462945** for the OTP Required option. Also, use the OTP value **4567** for your tests.
>
# Test Account Funding
Source: https://docs.payaza.africa/api-reference/momo-and-zar-collections/test-account-funding
/openapi.json post /subsidiary/funding/v1/process-collection
This endpoint funds is used to fund collections that have been initialized using your Test API Keys. It is only available on the sandbox environment
# Transaction Status Query
Source: https://docs.payaza.africa/api-reference/momo-and-zar-collections/transaction-status-query
/openapi.json get /subsidiary/collections/v1/check-status?transaction_reference={transaction_reference}&country_code={country_code}
This endpoint is used to check the status of a transaction using the transaction reference from the Momo Collection Request.
# XOF Process OTP
Source: https://docs.payaza.africa/api-reference/momo-and-zar-collections/xof-process-otp
/openapi.json post /subsidiary/collections/v1/process-otp
This endpoint processes the One Time Password that was retrieved by the user which would be used to complete the XOF(Orange only) Collection. For testing purposes, please use **2251114462945** for the OTP Required option. Also, use the OTP value **4567** for your tests..
# View Payaza Account Details
Source: https://docs.payaza.africa/api-reference/payaza-account/view-payaza-account-details
/openapi.json get /payaza-account/api/v1/mainaccounts/merchant/enquiry/main
This endpoint retrieves the Payaza account details for a merchant.
# Accept Or Reject Chargeback
Source: https://docs.payaza.africa/api-reference/refunds-and-chargebacks/accept-or-reject-chargeback
/openapi.json post /refund-chargeback/chargeback/merchant/api/accept_reject_chargeback
This endpoint is used to either accept or decline a chargeback request.
# Chargeback Request
Source: https://docs.payaza.africa/api-reference/refunds-and-chargebacks/chargeback-request
/openapi.json get /refund-chargeback/chargeback/merchant/api/chargeback_requests?transaction_reference={transaction_reference}&from={from}&to={to}&page={page}&size={size}
This endpoint is used to fetch chargeback requests directed to your Payaza account.
# Chargeback Transaction History
Source: https://docs.payaza.africa/api-reference/refunds-and-chargebacks/chargeback-transaction-history
/openapi.json get /refund-chargeback/chargeback/merchant/api/chargeback_transaction_history
The merchant can use this endpoint to fetch all chargeback transactions.
# Fetch Refund History
Source: https://docs.payaza.africa/api-reference/refunds-and-chargebacks/fetch-refund-history
/openapi.json get /refund-chargeback/refund/merchant/api/refund_history?from={from}&to={to}¤cy={currency}&page={page}&size={size}&refund_status={refund_status}&refund_reference={refund_reference}
The merchant uses this endpoint to fetch refund transaction history for card transactions. The data output can be filtered using a date range and/or status..
# Initiate Refund
Source: https://docs.payaza.africa/api-reference/refunds-and-chargebacks/initiate-refund
/openapi.json post /refund-chargeback/refund/merchant/api/refund
This endpoint is used to initiate a refund for a card transaction.
# Create Split Account
Source: https://docs.payaza.africa/api-reference/split-settlements/create-split-account
/openapi.json post /settlement/settlement/merchant/split-account
This creates a new split settlement account for the authenticated merchant. It can be referenced during Checkout transactions.
**Note:**
- A unique split account code is generated when a split account is successfully created.
- This code is required when configuring split settlements in the Checkout SDK.
- The bank code values for each respective bank can be retrieved here
# Delete Split Account
Source: https://docs.payaza.africa/api-reference/split-settlements/delete-split-account
/openapi.json delete /settlement/settlement/merchant/split-account/{id}
This deletes an existing split settlement account.
# Fetch Split Accounts
Source: https://docs.payaza.africa/api-reference/split-settlements/fetch-split-accounts
/openapi.json get /settlement/settlement/merchant/split-account?page=&size=
This retrieves all split settlement accounts belonging to the authenticated merchant.
# Update Split Account
Source: https://docs.payaza.africa/api-reference/split-settlements/update-split-account
/openapi.json put /settlement/settlement/merchant/split-account/{id}
This updates an existing split settlement account details.
**Note:**
- All request body parameters are optional. Include only the fields you want to update.
- Fields omitted from the request will retain their existing values.
# Create A Subaccount
Source: https://docs.payaza.africa/api-reference/sub-accounts/create-a-subaccount
/openapi.json post /payaza-account/api/v1/subaccounts/merchant
This endpoint is used to create a subaccount.
> **Notes:**
>
> 1. Please be advised that access to this API is available upon request. To initiate this process, kindly send an email to **support@payaza.africa**. You will be granted access once our team reviews and approves your request.
>
# View Payaza Sub Account Details
Source: https://docs.payaza.africa/api-reference/sub-accounts/view-payaza-sub-account-details
/openapi.json get /payaza-account/api/v1/subaccounts/merchant/enquiry/{payazaSubAccountReference}
This retrieves the Payaza subaccount details for a merchant using the subaccount account reference value in the Create A Subaccount API..
# Charge Now
Source: https://docs.payaza.africa/api-reference/subscription-charge/charge-now
/openapi.json post /subscription/api/v1/subscriptions/{id}/charge-now
This endpoint immediately triggers the next scheduled recurring charge for a subscription without waiting for the next billing cycle.
> **Note:** This endpoint charges the subscription's configured plan amount immediately and advances the billing cycle if the charge is successful.
# Create Custom Charge
Source: https://docs.payaza.africa/api-reference/subscription-charge/create-custom-charge
/openapi.json post /subscription/api/v1/subscriptions/{id}/charge-custom
This endpoint processes an off-cycle or custom charge for an active subscription.
> **Notes:**
> * By default, `countsAsCycle` is **false**.
> * When `countsAsCycle` is **false**, the subscription's billing cycle remains unchanged.
> * Set `countsAsCycle` to **true** if the custom charge should be treated as a scheduled billing cycle.
# Get Invoice
Source: https://docs.payaza.africa/api-reference/subscription-invoices/get-invoice
/openapi.json get /api/v1/invoices/{invoiceId}
This retrieves the details of a specific invoice.
# List Invoices
Source: https://docs.payaza.africa/api-reference/subscription-invoices/list-invoices
/openapi.json get /subscription/api/v1/invoices?status={status}&subscriptionId={subscriptionId}&from={from}&to={to}&page={page}&size={size}
This retrieves a paginated list of invoices belonging to the authenticated merchant.
# Cancel Subscription
Source: https://docs.payaza.africa/api-reference/subscription-lifecycle/cancel-subscription
/openapi.json patch /subscription/api/v1/subscriptions/{id}/cancel
This endpoint permanently cancels a subscription. Once cancelled, no further recurring charges will be attempted.
**Note:**
- Cancelling a subscription is a **terminal action**. Once cancelled, future billing stops immediately and `nextChargeDate` is cleared.
# Change Plan
Source: https://docs.payaza.africa/api-reference/subscription-lifecycle/change-plan
/openapi.json post /subscription/api/v1/subscriptions/{id}/change-plan
This changes the subscription to another pricing plan either immediately or at the next billing cycle.
**Notes:**
- `effective` defaults to **NEXT_CYCLE** if not supplied.
- When `effective` is **NEXT_CYCLE**, the new plan is stored as the pending plan and becomes active at the next successful billing cycle.
- When `effective` is **IMMEDIATELY**, the subscription is switched to the new plan immediately.
- Attempting to change to the current plan or modifying a terminal subscription returns a validation error.
# Pause Subscription
Source: https://docs.payaza.africa/api-reference/subscription-lifecycle/pause-subscription
/openapi.json patch /subscription/api/v1/subscriptions/{id}/pause
Pauses recurring billing for a subscription. Billing remains suspended until the subscription is resumed manually or automatically on the specified resume date.
**Note:**
- If `resumeAt` is omitted, the subscription remains paused until it is resumed manually.
# Resume Subscription
Source: https://docs.payaza.africa/api-reference/subscription-lifecycle/resume-subscription
/openapi.json patch /subscription/api/v1/subscriptions/{id}/resume
This resumes a paused subscription and schedules the next recurring charge.
**Note:**
- Only subscriptions with a status of **PAUSED** can be resumed.
# Create Plan
Source: https://docs.payaza.africa/api-reference/subscription-plans/create-plan
/openapi.json post /subscription/api/v1/subscription-plans
This endpoint creates a new subscription plan.
**Note:**
- Save the generated `planCode` after creating a plan. This value is required when creating subscriptions.
# Get Plan Details
Source: https://docs.payaza.africa/api-reference/subscription-plans/get-plan-details
/openapi.json get /subscription/api/v1/subscription-plans/{planCode}
This endpoint retrieves the details of a specific subscription plan.
# List Plans
Source: https://docs.payaza.africa/api-reference/subscription-plans/list-plans
/openapi.json get /subscription/api/v1/subscription-plans?page={page}&size={size}&status={status}
This endpoint retrieves a paginated list of subscription plans that have been created by the merchant.
# Update Plan Details
Source: https://docs.payaza.africa/api-reference/subscription-plans/update-plan-details
/openapi.json patch /subscription/api/v1/subscription-plans/{planCode}
This endpoint updates the editable properties of an existing subscription plan, including its name, description, trial period, and billing limit.
# Get Subscription
Source: https://docs.payaza.africa/api-reference/subscription-reads/get-subscription
/openapi.json get /subscription/api/v1/subscriptions/{id}
It retrieves the details of a specific subscription.
# List Subscription
Source: https://docs.payaza.africa/api-reference/subscription-reads/list-subscription
/openapi.json get /subscription/api/v1/subscriptions?page={page}&size={size}&status={status}
It retrieves a paginated list of subscriptions belonging to the authenticated merchant.
# Subscription Charge History
Source: https://docs.payaza.africa/api-reference/subscription-reads/subscription-charge-history
/openapi.json get /subscription/api/v1/subscriptions/{id}/charges?page={page}&size={size}
It retrieves the billing history for a subscription.
# Subscription Event History
Source: https://docs.payaza.africa/api-reference/subscription-reads/subscription-event-history
/openapi.json get /subscription/api/v1/subscriptions/{id}/events?page={page}&size={size}
This retrieves the lifecycle events associated with a subscription. Lifecycle events provide an audit trail of significant actions performed on a subscription, such as creation, successful charges, payment failures, pauses, resumes, cancellations, plan changes, and other status transitions..
# Upcoming Charges
Source: https://docs.payaza.africa/api-reference/subscription-reads/upcoming-charges
/openapi.json get /subscription/api/v1/subscriptions/{id}/upcoming?count=5
It returns the upcoming scheduled charges for a subscription.
# Create Subscription
Source: https://docs.payaza.africa/api-reference/subscriptions/create-subscription
/openapi.json post /subscription/api/v1/subscriptions
This endpoint creates a new subscription for a customer, enrolls the customer's card, and initiates the first payment where applicable.
### Important Notes
* **`cardDetails`** is mandatory when creating a subscription.
* If no trial period is configured, the first charge is attempted immediately after the card is enrolled.
* If a trial period is configured, the subscription is created with a status of **TRIALING**. The card is enrolled immediately, but the first charge is deferred until the trial period ends.
* When additional customer authentication is required, the subscription is created with a status of **REQUIRES_ACTION**, and the response includes the 3D Secure challenge details.
* Creating another active subscription using the same `customerEmail` returns a **409 Conflict** response.
* Before the first successful payment, the subscription remains in the **INCOMPLETE** state.
* The card service determines the charge mode (**DIRECT_CHARGE**, **TOKENIZATION**, or **AGREEMENT_BASED**) during card enrollment and returns it in the response. The subscription service stores this value for future recurring billing.
# Bank Codes
Source: https://docs.payaza.africa/api-reference/transfers/bank-codes
/openapi.json get /payaza-account/api/v1/mainaccounts/merchant/banks/{currency_code}
The Bank Codes API is used to retrieve the bank codes available for each country that would be used in the Initiate A Transfer request.
# Get Account Name Enquiry
Source: https://docs.payaza.africa/api-reference/transfers/get-account-name-enquiry
/openapi.json post /payaza-account/api/v1/mainaccounts/merchant/provider/enquiry
The Account Name Enquiry API is used to retrieve the account details of a beneficiary using its account number.
# Initiate A Transfer
Source: https://docs.payaza.africa/api-reference/transfers/initiate-a-transfer
/openapi.json post /payout-receptor/payout
Send funds from your Payaza account to a bank account or mobile wallet. Supports single and bulk payouts. See the full [Transfers guide](/guides/transfers) for a step-by-step walkthrough.
**Before you call this endpoint:**
- Your server IP address must be whitelisted on the Payaza Dashboard under **Settings → Developers → IP Whitelisting** (live environment only).
- Your transaction PIN must be set up on the dashboard under **Settings → Profile → Security**.
- The `account_reference` is retrieved from the [View Payaza Account Details](/api-reference/payaza-account/view-payaza-account-details) endpoint.
- Bank codes for each supported country are available here
- Cross-border payouts outside Nigeria are not enabled by default — email [support@payaza.africa](mailto:support@payaza.africa) to activate this on your account.
# Transaction Status Query
Source: https://docs.payaza.africa/api-reference/transfers/transaction-status-query
/openapi.json get /payaza-account/api/v1/mainaccounts/merchant/transaction/{transaction_reference}
This retrieves the details of a transaction using the transaction reference value that was placed in the Initiate A Transfer request.
# Create Static/Dynamic Virtual Account
Source: https://docs.payaza.africa/api-reference/virtual-accounts/create-staticdynamic-virtual-account
/openapi.json post /merchant-collection/merchant/virtual_account/generate_virtual_account
This API endpoint allows you to create dynamic virtual accounts with a duration of 30 mins and reserved/static virtual accounts that are permanent. Our virtual accounts guide can be found [here](/guides/virtual-accounts)
# Fund Test Virtual Account
Source: https://docs.payaza.africa/api-reference/virtual-accounts/fund-test-virtual-account
/openapi.json post /merchant-collection/payaza/virtual_account/fund_test_virtual_account
This endpoint funds the test virtual accounts. Please note that this API is just for sandbox collections.
# Get Virtual Account Status
Source: https://docs.payaza.africa/api-reference/virtual-accounts/get-virtual-account-status
/openapi.json get /merchant-collection/merchant/virtual_account/detail/virtual_account/{virtualAccountNumber}
This endpoint retrieves the status of a specific virtual account using the account number. It works for only static virtual accounts.
# Transaction Status Query
Source: https://docs.payaza.africa/api-reference/virtual-accounts/transaction-status-query
/openapi.json get /merchant-collection/transfer_notification_controller/transaction-query?transaction_reference={transactionReference}
This endpoint is used to check the status of a transaction using the transaction reference.
# Apple Pay & Google Pay
Source: https://docs.payaza.africa/guides/apple-google-pay
Accept wallet payments from customers using Apple Pay and Google Pay. Initiate the payment server-side and confirm the outcome via webhook or status query.
## Overview
Payaza supports Apple Pay and Google Pay as collection channels. You initiate the payment from your server using the mobile payment API which generates a payment URL for the customer to access, and the customer authorizes the charge through their device's native wallet experience.
Apple Pay works on Safari (iOS and macOS). Google Pay works on Chrome and
Android browsers. Always provide a fallback payment method for customers who
do not have a supported wallet configured on their device.
***
## Key Requirements
Use your **public API key** encoded in Base64 for all wallet payment requests.
See the [Authentication guide](/guides/authentication) for setup instructions.
Set these headers on every request:
```json theme={null}
{
"Authorization": "Payaza ",
"Content-Type": "application/json"
}
```
Make sure your Collection webhook URL is saved on the dashboard. See the [Webhooks guide](/guides/webhooks) for setup instructions.
***
## Endpoints
| Method | Endpoint | Description |
| ------ | ------------------------------------------------------------------------- | --------------------------------------------------- |
| `POST` | `/merchant-collection/mobile_payment/initiate` | Initiate an Apple Pay or Google Pay payment |
| `GET` | `/merchant-collection/transfer_notification_controller/transaction-query` | Query transaction status by `transaction_reference` |
***
## How it works
Your server calls the Initiate endpoint with the customer details, amount,
and `payment_option` set to `"APPLEPAY"` or `"GOOGLEPAY"` which generates a
payment URL.
The customer views the payment URL and sees the native Apple Pay or Google
Pay checkout modal on their device and authenticates with Face ID, Touch ID,
or their device PIN.
Payaza fires a webhook to your configured URL when the payment completes or
fails. Use the Transaction Status Query endpoint as a fallback if a webhook
is not received in time.
***
## Step 1 — Initiate the payment
```bash cURL — Apple Pay theme={null}
curl --request POST \
--url https://api.payaza.africa/live/merchant-collection/mobile_payment/initiate \
--header 'Authorization: Payaza ' \
--header 'Content-Type: application/json' \
--data '{
"amount": 2,
"first_name": "John",
"last_name": "Doe",
"payment_option": "APPLEPAY",
"description": "Support",
"email_address: "johndoe@email.com",
"transaction_reference": "TX20251109",
"redirect_url": "https://redirect.url/success",
"cancel_url": "https://redirect.urlcancel",
"error_url": "https://redirect.url/error",
"country_code": "NGN",
"currency_code": "USD"
}'
```
```bash cURL — Google Pay theme={null}
curl --request POST \
--url https://api.payaza.africa/live/merchant-collection/mobile_payment/initiate \
--header 'Authorization: Payaza ' \
--header 'Content-Type: application/json' \
--data '{
"amount": 2,
"first_name": "John",
"last_name": "Doe",
"payment_option": "GOOGLEPAY",
"description": "Support",
"email_address: "johndoe@email.com",
"transaction_reference": "TX20251109",
"redirect_url": "https://redirect.url/success",
"cancel_url": "https://redirect.urlcancel",
"error_url": "https://redirect.url/error",
"country_code": "NGN",
"currency_code": "USD"
}'
```
### Request parameters
| Parameter | Type | Required | Description |
| ----------------------- | -------- | -------- | ---------------------------------------------------------------------- |
| `transaction_reference` | `string` | Yes | Your unique reference for this payment. Must be unique per transaction |
| `payment_option` | `string` | Yes | Wallet type — `"APPLEPAY"` or `"GOOGLEPAY"` |
| `amount` | `number` | Yes | Amount to collect from the customer |
| `currency_code` | `string` | Yes | ISO currency code — e.g. `"USD"`, `"NGN"` |
| `country_code` | `string` | Yes | ISO currency code for the transaction country — e.g. `"NGN"` |
| `description` | `string` | Yes | Description shown on the customer's payment confirmation |
| `email_address` | `string` | Yes | Customer's email address. |
| `first_name` | `string` | Yes | Customer's first name |
| `last_name` | `string` | Yes | Customer's last name |
| `redirect_url` | `string` | Yes | URL to redirect the customer to after successful payment |
| `cancel_url` | `string` | Yes | URL to redirect the customer to if they cancel |
| `error_url` | `string` | Yes | URL to redirect the customer to on payment error |
### Sample response
```json theme={null}
{
"status": true,
"message": "payment initiated successfully",
"data": {
"error_url": "https://redirect.url/error",
"merchant_reference": "TX20251109",
"payment_option": "GOOGLEPAY",
"transaction_amount": 2,
"slug_name": "dev-guide-test",
"currency": "USD",
"paymentUrl": "{{paymentUrl}}",
"transaction_reference": "TX20251109",
"cancel_url": "https://redirect.urlcancel",
"redirect_url": "https://redirect.url/success"
}
}
```
***
## Step 2 — Query transaction status
Use this endpoint to confirm the final outcome of a payment. Call it after initiating, or as a fallback if a webhook is not received within your expected timeout.
```bash cURL theme={null}
curl --request GET \
--url 'https://api.payaza.africa/live/merchant-collection/transfer_notification_controller/transaction-query?transaction_reference=TX20251109' \
--header 'Authorization: Payaza '
```
```json Successful theme={null}
{
"message": "Transaction data found",
"data": {
"transaction_reference": "P-C-20260306-41XUJ9AISE",
"amount_received": 5,
"transaction_fee": 0.05,
"transaction_status": "Completed",
"sender_name": "Test Test",
"sender_account_number": null,
"source_bank_name": "NA",
"initiated_date": "2026-03-06 17:14:44.414486",
"current_status_date": "2026-03-06 17:15:10.136189",
"currency": "USD",
"session_id": "TRN99637191655A",
"merchant_transaction_reference": "TX213139dz",
"transaction_type": "Apple Pay",
"virtual_account_number": null,
"status_reason": null
},
"success": true
}
```
```json Initialized theme={null}
{
"message": "Transaction data found",
"data": {
"transaction_reference": "P-C-20260313-I840WFC6LS",
"amount_received": 5.33,
"transaction_fee": 0.33,
"transaction_status": "Initialized",
"sender_name": null,
"sender_account_number": null,
"source_bank_name": "NA",
"initiated_date": "2026-03-13 15:13:10.521614",
"current_status_date": null,
"currency": "USD",
"session_id": "TRN68681366586A",
"merchant_transaction_reference": "TX213139dx",
"transaction_type": "Apple Pay",
"virtual_account_number": null,
"status_reason": null
},
"success": true
}
```
```json Failed theme={null}
{
"message": "Transaction data found",
"data": {
"transaction_reference": "P-C-20260313-I840WFC6LS",
"amount_received": 5.33,
"transaction_fee": 0.33,
"transaction_status": "Failed",
"sender_name": null,
"sender_account_number": null,
"source_bank_name": "NA",
"initiated_date": "2026-03-13 15:13:10.521614",
"current_status_date": "2026-03-13 15:28:33.619368",
"currency": "USD",
"session_id": "TRN68681366586A",
"merchant_transaction_reference": "TX213139dy",
"transaction_type": "Apple Pay",
"virtual_account_number": null,
"status_reason": "Transaction status: CANCELLED"
},
"success": true
}
```
***
## Errors
| Error | Cause | Fix |
| -------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------- |
| `"Kindly check the provided Authorization"` | Invalid or missing API key | Re-encode your key and use the `Payaza ` format |
| `"Transaction Reference already exists"` | Reused `transaction_reference` | Generate a unique reference per payment attempt |
| `"Payment option can be either GOOGLEPAY or APPLEPAY"` | Invalid `payment_option` value | Pass exactly `"GOOGLEPAY"` or `"APPLEPAY"` |
| `"Payment option is currently not available via this channel"` | Unsupported currency code | Use a supported currency for wallet payments |
| `"Transaction not found"` | `transaction_reference` does not exist | Verify the reference and retry |
See the full [Errors reference](/guides/errors) for more detail.
***
## What's next
Accept card payments directly via the API.
Receive real-time payment notifications from Payaza.
# Auth, Capture, and Void
Source: https://docs.payaza.africa/guides/auth-capture-void
Pre-authorize a card, capture the funds later, or void the authorization before settlement. Use this flow when the final charge amount is not known at the time of payment.
## Overview
The Auth/Capture/Void flow splits a card charge into two steps:
1. **Authorize** — reserve the funds on the customer's card without charging them yet
2. **Capture** — settle the reserved funds once you are ready (e.g. after shipping or fulfillment)
3. **Void** (optional) — cancel the authorization before capture if the order is cancelled
This is useful for hotel holds, ride reservations, or any situation where the final amount is confirmed after the initial authorization.
***
## Key Requirements
Use your **public API key** encoded in Base64. See the [Authentication
guide](/guides/authentication) for setup instructions.
Set these headers on every request:
```json theme={null}
{
"Authorization": "Payaza ",
"Content-Type": "application/json"
}
```
***
## Endpoints
| Method | Endpoint | Description |
| ------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `POST` | `/card/auth_capture/authorize` | Pre-authorize a card and reserve funds |
| `POST` | `/card/auth_capture/capture` | Capture (settle) a previously authorized amount |
| `POST` | `/card/auth_capture/void` | Void an authorization before it is captured |
| `GET` | `/card/auth_capture/authorize/{authorization_reference}` | Retrieve a single authorization by reference |
| `GET` | `/card/auth_capture/authorize` | List authorizations with optional filters (`status`, `page`, `size`, `from_date`, `to_date`) |
***
## How it works
Call the Authorize endpoint with the customer's card details and the amount
to reserve. On success, you receive an `authorization_reference` — store
this.
When you are ready to charge (e.g. after order fulfillment), call the
Capture endpoint with the `authorization_reference`. The reserved funds are
settled to your account.
If the order is cancelled before capture, call the Void endpoint with the
`authorization_reference` to release the hold on the customer's card.
Authorizations that are neither captured nor voided will expire automatically.
The expiry window depends on the card network. Implement monitoring to capture
or void authorizations before they expire.
***
## Best-fit scenarios
* **Inventory-dependent orders** — Authorize at checkout, capture after stock is confirmed
* **Hotel and travel holds** — Reserve funds at booking, settle the final amount at check-out
* **Risk-reviewed transactions** — Hold funds while manual review is completed before capture
***
## What's next
Standard card charges without the auth/capture split.
Reverse a captured payment or respond to a chargeback.
# Authentication
Source: https://docs.payaza.africa/guides/authentication
All Payaza API requests are authenticated using your API key. Learn how to retrieve, encode, and use your key correctly.
## How authentication works
Every Payaza API request requires an `Authorization` header. The format is:
```
Authorization: Payaza
```
Two things are different from most APIs:
1. The prefix is **`Payaza`** — not `Bearer`
2. Your API key must be **Base64-encoded** before use
***
## Step 1 — Retrieve your API key
Go to [business.payaza.africa](https://business.payaza.africa) and log in to your account.
Click **Settings** in the left sidebar, then select **Developers** from the dropdown.
Click the **Generate Keys** button to create your API keys. Toggle between **Test Mode** and **Live Mode** to retrieve the key for each environment.
Never expose your API key in client-side code, browser JavaScript, or a public repository. If a key is ever compromised, regenerate it immediately from the dashboard.
***
## Step 2 — Encode your key in Base64
Your API key must be Base64-encoded before placing it in the `Authorization` header.
```bash Terminal theme={null}
echo -n "your-api-key-here" | base64
```
```javascript Node.js theme={null}
const apiKey = "your-api-key-here";
const encodedKey = Buffer.from(apiKey).toString("base64");
// Use encodedKey in your Authorization header
```
```python Python theme={null}
import base64
api_key = "your-api-key-here"
encoded_key = base64.b64encode(api_key.encode()).decode()
# Use encoded_key in your Authorization header
```
```php PHP theme={null}
$api_key = "your-api-key-here";
$encoded_key = base64_encode($api_key);
// Use $encoded_key in your Authorization header
```
***
## Step 3 — Make an authenticated request
These are the possible headers that can be added to a Payaza API request:
| Header | Required | Value |
| --------------- | -------------- | ----------------------------- |
| `Authorization` | Yes | `Payaza ` |
| `X-TenantID` | Depends on API | `test` or `live` |
| `Content-Type` | Yes (POST/PUT) | `application/json` |
```bash cURL theme={null}
curl --request GET \
--url https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts \
--header 'Authorization: Payaza UFo4748S0xJVkUtSJDS5RThDQzEtQjAzMS00RUNBLTgwOTctRUVCMjA5NzJENTY0' \
--header 'X-TenantID: test'
```
```javascript Node.js theme={null}
const axios = require("axios");
const apiKey = "your-api-key-here";
const encodedKey = Buffer.from(apiKey).toString("base64");
const { data } = await axios.get(
"https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts",
{
headers: {
Authorization: `Payaza ${encodedKey}`,
"X-TenantID": "test",
},
}
);
```
```python Python theme={null}
import base64
import requests
api_key = "your-api-key-here"
encoded_key = base64.b64encode(api_key.encode()).decode()
response = requests.get(
"https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts",
headers={
"Authorization": f"Payaza {encoded_key}",
"X-TenantID": "test",
},
)
data = response.json()
```
```php PHP theme={null}
$api_key = "your-api-key-here";
$encoded_key = base64_encode($api_key);
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Payaza " . $encoded_key,
"X-TenantID: test",
],
]);
$response = json_decode(curl_exec($curl), true);
curl_close($curl);
```
`X-TenantID` is required for some APIs but not all. For APIs that require it, use `test` during development and `live` in production. See the [Required headers by API](#required-headers-by-api) table below for a full breakdown.
***
## Required headers by API
Different Payaza APIs require different combinations of headers. Use this table as a quick reference before making requests.
| API | `Authorization` | `X-TenantID` | `X-ProductID` | `Content-Type` |
| ---------------------------------- | --------------------- | ---------------- | ------------- | ------------------ |
| Card Collections | `Payaza ` | Not required | Not required | `application/json` |
| Momo / XOF / ZAR / SLE Collections | `Payaza ` | `test` or `live` | `app` | `application/json` |
| Apple Pay / Google Pay | `Payaza ` | Not required | Not required | `application/json` |
| Transfers (Payouts) | `Payaza ` | `test` or `live` | Not required | `application/json` |
| Virtual Accounts | `Payaza ` | Not required | Not required | `application/json` |
| Sub-accounts | `Payaza ` | `test` or `live` | Not required | `application/json` |
| Refunds & Chargebacks | `Payaza ` | Not required | Not required | `application/json` |
| Account Enquiry | `Payaza ` | `test` or `live` | Not required | `application/json` |
`X-ProductID: app` is only required for the Momo, XOF, ZAR, and SLE collections API (`/subsidiary/collections/v1/...`). All other APIs do not require it.
`X-TenantID` is **not required** for Apple Pay, Google Pay, Virtual Accounts, Refunds, and Chargebacks. All other listed APIs require `X-TenantID` set to `test` (development) or `live` (production).
***
## Test vs Live environments
Payaza uses a single API base URL (`https://api.payaza.africa/live/`) for both environments. The `/live/` segment in the URL is a fixed path prefix — it does **not** change between environments. Only the `X-TenantID` header and the API key distinguish test from live.
| | Test | Live |
| ------------ | --------------------------------------- | ---------------------------------------- |
| `X-TenantID` | `test` | `live` |
| API key | Generated in **Test Mode** on dashboard | Generated in **Live Mode** on dashboard |
| Transactions | Not processed or settled | Real transactions processed and settled |
| KYB required | No | Yes — must be approved before going live |
You can begin testing immediately after creating your Payaza account. KYB (Know Your Business) verification is only required to access the live environment.
***
## Authentication errors
A failed authentication returns this response:
```json theme={null}
{
"message": "Authentication failed",
"status": false,
"retry_count": 0
}
```
| Cause | Fix |
| ------------------------------------------------ | -------------------------------------------------------- |
| Missing `Authorization` header | Add the header to your request |
| Raw (non-encoded) API key used | Base64-encode your key before use |
| Wrong prefix — e.g. `Bearer` instead of `Payaza` | Change the prefix to `Payaza` |
| Test key used with `X-TenantID: live` | Match the key to the correct environment |
| Key was regenerated on the dashboard | Copy the new key, encode it, and update your integration |
***
## What's next
Walk through account setup and make your first API call end-to-end.
Receive real-time payment notifications when events happen on your account.
Start sending payouts to bank accounts and mobile wallets.
A reference for all API error responses and how to resolve them.
# Card Collections
Source: https://docs.payaza.africa/guides/card-collection
This guide explains how to collect payments from customers using debit and credit cards via the Payaza Card Charge API — including 3DS authentication, transaction status checks, and refunds.
## Key Requirements
Retrieve your API keys from your dashboard by following the steps on our
[Authentication](/guides/authentication) page. Use your **public API key** for
all card collection requests.
Set the following headers on every request:
```json theme={null}
{
"Authorization": "Payaza "
}
```
Make sure your webhook URL is saved on the dashboard and configured to accept `POST` requests. See our [Webhooks guide](/guides/webhooks) for setup instructions.
***
## Supported currencies
Card collections are supported for both NGN and USD.
For **NGN cards**, the `pin` parameter is required in the Card Charge request.
***
## How card collections work
Card payments on Payaza can follow one of two flows depending on whether the card is enrolled in 3D Secure (3DS):
1. Your server calls **Card Charge** with the customer and card details. 2.
The response returns `do3dsAuth: false` and `paymentCompleted: true`. 3. If a
`callback_url` was provided, the customer is redirected to it with the final
payment result in the POST body. 4. If no `callback_url` was provided, handle
the result in the same page via the `window.message` `postMessage` event
listener.
1. *(Optional)* Call **Check 3DS Availability** upfront to determine if the card requires 3DS.
2. Your server calls **Card Charge** with the customer and card details.
3. The response returns `do3dsAuth: true` along with `threeDsUrl`, `formData`, and `threeDsHtml`.
4. Your frontend injects the `threeDsHtml` into the DOM — this auto-submits a form inside an iframe that redirects the customer to the card issuer's 3DS challenge page.
5. The customer completes the bank OTP or authentication challenge.
6. **If `callback_url` was provided:** the issuer redirects the customer back to your `callback_url` via a `POST` request containing the final payment result.
7. **If no `callback_url` was provided:** the result is posted back to your page via `window.postMessage` and captured by a `window.addEventListener("message", ...)` listener on the parent page.
The `threeDsHtml` field contains a self-submitting HTML form that must be rendered directly in the DOM — do not strip the `
```
**Key points about this document:**
* The iframe (`challengeFrame`) renders the card issuer's 3DS authentication page — the customer sees their bank's OTP or biometric prompt inside it.
* `result.formData` maps to the `creq` (challenge request) value that the ACS (Access Control Server) expects. Do not modify it.
* `result.threeDsUrl` is the ACS URL generated by Payaza for that specific transaction. It changes with every charge.
* Replace `alert(...)` with your actual UI logic — redirect the customer, update the order status, or render a success/failure component.
***
## Step 2 — Check Transaction Status
Retrieve the final status of a card transaction by its `transaction_reference`. Use this as a server-side fallback when a webhook is not received within your expected timeout.