Api Documentation

Nigeria (NGN) Integration Guide

Overview

Nigeria has multiple payment methods for accepting customer payments and processing payouts. This guide covers the available payment channels and how to integrate them.

Currency: NGN (Nigerian Naira)
Supported Methods: Virtual Accounts, Checkout Payment Links, Opay & PalmPay, Bank Transfer

Available Payment Methods

Channel Code	Payment Method	Type	Description
300041	Virtual Accounts	Payin	Dynamic virtual bank account for customer deposits
300044	Checkout Payment Links	Payin	Payment link/checkout page for bank payments
300045	Opay & PalmPay	Payin	Direct payments via Opay and PalmPay wallets
300043	Bank Transfer	Payout	Bank transfer disbursements to customer accounts

Payin Methods

1. Virtual Accounts (Channel: 300041)

Customers receive a dynamic virtual bank account to transfer funds. After initiation, display the account details to the customer for them to complete the transfer.

Flow: Initiate → Display virtual account → Customer transfers → Webhook confirmation

2. Checkout Payment Links (Channel: 300044)

Generate a checkout payment link that customers can use to pay via cards, bank transfer, or other supported methods.

Flow: Initiate → Receive payment link → Customer completes payment → Webhook confirmation

3. Opay & PalmPay (Channel: 300045)

Direct integration with Opay and PalmPay wallets for instant payments.

Flow: Initiate with customer wallet details → Customer authorizes → Webhook confirmation

Payout Methods

Bank Transfer (Channel: 300043)

Disburse funds directly to customer bank accounts via NUBAN (Nigeria Uniform Bank Account Number).

Required fields: Bank code, account number, account name

Request Fields Reference

Field	Type	Description	Required
wallet_no	string	Your business wallet account number	Yes
reference	string	Unique order reference per request	Yes
acc_name	string	Customer/Recipient name	Yes
acc_no	string	Customer phone number (for payins) or bank account number (for payouts)	Yes
email	string	Customer email address	Yes
amount	numeric	Transaction amount (no commas)	Yes
currency	string	Currency code: `NGN`	Yes
channel	numeric	Payment channel code (300041, 300044, 300045, 300043)	Yes
description	string	Transaction description	Yes
result_url	string	Webhook URL for payment status callbacks	Yes
bank_code	string	Bank code (required for 300045 Opay/PalmPay and 300043 payouts)	Conditional

Bank Codes for Opay & PalmPay

100004	Opay	Opay wallet collections & payouts
100033	PalmPay	PalmPay wallet collections & payouts

For other Nigerian banks, see Bank Codes Reference.

Quickstart: Virtual Account Payin

Send a POST request to /api/v2/payment/ with channel 300041
Receive virtual account details in the response
Display the account details to your customer
Customer transfers the exact amount to the virtual account
Receive payment confirmation via webhook on your result_url

Example Request: Virtual Account Payin (Channel: 300041)

{
    "wallet_no": "XXXXXXX",
    "reference": "CORNGN0089123036",
    "acc_name": "Test Customer",
    "acc_no": "08012345678",
    "email": "customer@example.com",
    "currency": "NGN",
    "amount": 100,
    "channel": 300041,
    "description": "Order payment",
    "result_url": "https://your-server.com/webhook"
}

Example Response: Virtual Account Payin

{
    "success": true,
    "message": "Successfully initiated",
    "data": {
        "acc_name": "Test Customer",
        "acc_no": "08012345678",
        "description": "Order payment",
        "transaction_id": "126072834240",
        "reference": "CORNGN0089123036",
        "status": "PROCESSING",
        "amount": 100,
        "charges": 0,
        "currency": "NGN",
        "status_description": "Account generated successfully",
        "date": "2026-07-28 13:23:15 PM",
        "fetched_at": "2026-07-28 13:23:21 PM",
        "virtual_account": {
            "account_number": "1251258358",
            "account_name": "BOBPLUS AFRICA Checkout",
            "bank_name": "78 Finance Company limited (Bank78)",
            "expires": "2026-07-28 12:23:21 PM"
        }
    }
}

Example Request: Opay & PalmPay Collection (Channel: 300045)

{
    "wallet_no": "XXXXXXX",
    "reference": "CORWALLET0199065",
    "acc_name": "Test Customer",
    "acc_no": "08012345678",
    "email": "customer@example.com",
    "currency": "NGN",
    "amount": 100,
    "channel": 300045,
    "bank_code": "100004",
    "description": "Test opay payment",
    "result_url": "your-callback-url"
}

Note: bank_code for Opay = 100004, PalmPay = 100033

Example Response: Opay & PalmPay Collection

{
    "success": true,
    "message": "Successfully initiated",
    "data": {
        "acc_name": "Test",
        "acc_no": "08012345678",
        "description": "Test opay payment",
        "transaction_id": "126072844637",
        "reference": "CORWALLET0199065",
        "status": "PROCESSING",
        "amount": 100,
        "charges": 0,
        "currency": "NGN",
        "status_description": "Payment initialized successfully",
        "date": "2026-07-28 16:39:10 PM",
        "fetched_at": "2026-07-28 16:39:15 PM",
        "bank_code": "100004",
        "bank_name": "bank_name",
        "redirect_url": "https://opaycheckouturl"
    }
}

Example Request: Payment Links Checkout (Channel: 300044)

{
    "wallet_no": "XXXXXXX",
    "reference": "CORCHK00012349970",
    "acc_name": "Test Customer",
    "acc_no": "08012345678",
    "email": "customer@example.com",
    "currency": "NGN",
    "amount": 100,
    "channel": 300044,
    "description": "Order payment",
    "result_url": "https://your-server.com/webhook"
}

Example Response: Payment Links Checkout

{
    "success": true,
    "message": "Successfully initiated",
    "data": {
        "acc_name": "Test",
        "acc_no": "08012345678",
        "description": "checkout test payment",
        "transaction_id": "126073182949",
        "reference": "CORCHK000123499780",
        "status": "PROCESSING",
        "amount": 100,
        "charges": 0,
        "currency": "NGN",
        "status_description": "Payment initialized successfully",
        "date": "2026-07-31 16:54:14 PM",
        "fetched_at": "2026-07-31 16:54:19 PM",
        "redirect_url": "https://redirect-url-to-pay"
    }
}

Example Request: Bank Transfer Payout (Channel: 300043)

{
    "wallet_no": "XXXXXXX",
    "reference": "CORNGNPAY00123744",
    "acc_name": "Elizabeth Julius",
    "acc_no": "8127586313",
    "bank_code": "100004",
    "email": "customer@example.com",
    "currency": "NGN",
    "amount": 100,
    "channel": 300043,
    "description": "Test NGN Opay payout"
}

Note: bank_code for Opay = 100004, PalmPay = 100033. Other banks have different codes. See Bank Codes for the full list.

Example Response: Bank Transfer Payout

{
    "success": true,
    "message": "Successfully initiated",
    "data": {
        "acc_name": "Elizabeth Julius",
        "acc_no": "8127586313",
        "description": "Test NGN Opay payout",
        "transaction_id": "126072846655",
        "reference": "CORNGNPAY00123744",
        "status": "PENDING",
        "amount": 100,
        "charges": 0,
        "currency": "NGN",
        "status_description": "initiated, pending payment",
        "date": "2026-07-28 17:07:37 PM",
        "fetched_at": "2026-07-28 17:07:37 PM",
        "bank_code": "100004",
        "bank_name": "bank name"
    }
}

Bank Codes Reference

For payouts, use the appropriate bank code. See Bank Codes for the full list of Nigerian bank codes.

Webhook & Callbacks

Payment status updates are sent to your result_url. Ensure your server can handle POST requests with the transaction status.

For detailed callback handling, see Callback Response Documentation.

Important Notes

Virtual Accounts (300041): The virtual account has an expiry time. Display this to customers so they complete the transfer before expiry.
Checkout & Opay/PalmPay (300044, 300045): These return a redirect_url. Redirect your customer to this URL to complete payment.
Bank Payouts (300043): Ensure the acc_name matches the bank account holder's name exactly to avoid failed transactions.
Bank Codes: For Opay use 100004, for PalmPay use 100033. Other banks have different codes - see Bank Codes.
References: Each reference must be unique per transaction. Duplicate references will be rejected.

Response Status Codes

Status	Description
PROCESSING	Transaction initiated, awaiting customer action or processing
PENDING	Transaction is pending completion
SUCCESS	Transaction completed successfully
FAILED	Transaction failed

Security Best Practices

Always use HTTPS for all API requests.
Keep your private key secure and never share it.
Verify the signature on the server side for every request.
Implement webhook signature verification to prevent fraud.
Validate all callback data before processing.

Terms of Use & Legal

By using this API, you agree to our Terms of Service and Privacy Policy. Do not share sensitive data or credentials.