Skip to main content

Pay-In · Nigeria

TOPPAY TeamAbout 4 min

Overview

The Pay-In API lets merchants initiate collection transactions from customers. This page covers Nigeria (country code ng) and supports two order placement modes:

ModePathDescription
Cashier mode/pay/prePayDefault mode. Returns cashierUrl for redirecting the customer to the platform H5 cashier to complete payment
API mode/pay/transOrderSpecify method in the request to receive payData / payDataType directly (VA account, wallet redirect link, etc.)

method (Pay-In payment codes for Nigeria) is listed in Regional Payment Guide — Nigeria.

Integration note

Cashier mode is enabled by default. To integrate API mode, contact support to request merchant whitelist access before integration.

Request Header

Shared by both modes:

FieldRequiredTypeDescription
Content-TypeMStringHTTP content type specification
Fixed value: application/json
Required for proper request parsing

Cashier Mode (prePay)

After placing a pre-order, the merchant receives cashierUrl and redirects the customer to the platform cashier to select a payment method and complete payment.

Request URL

Domain: Prefer unified host openapi.toppayment.com (path unchanged); legacy country domain (e.g. global-ng-openapi.toppayment.com) remains available.

EnvironmentURL
Sandboxhttps://openapi.toppayment.com/sandbox/ng/pay/prePay
Productionhttps://openapi.toppayment.com/ng/pay/prePay

Request Body

FieldRequiredTypeDescription
mchNoMString(32)Merchant number
Unique merchant identifier assigned by the platform
Used for merchant authentication and transaction routing
orderNumMString(64)Merchant order number
Unique transaction identifier
Format: Alphanumeric string
Used for transaction tracking and reference
amountMNumber(32,8)Transaction amount
Numeric type
Currency is Naira (NGN). Decimals are not allowed for Nigeria — pass an integer
Example: 5000
productDetailMString(100)Product detail
Transaction purpose or description
UTF-8 string
methodOString(16)Payment method (Nigeria)
Optional; if omitted, the customer selects on the cashier. Examples: PAGA, PALMPAYBANK, OPAY, PALMPAY — full list: Regional Payment Guide — Nigeria
timestampMString(13)Timestamp
Request timestamp in milliseconds
Example: 1749451858772
customerNameMString(64)Customer name
Payer name
UTF-8 string
customerEmailMString(64)Customer email
Payer email address
Valid email format
customerPhoneMString(32)Mobile number
Format: 234 followed by a 10-digit mobile number whose first digit is 7, 8, or 9
Example: 2348031234567
expiryPeriodONumber(1–9999)Expiry period
Order validity in minutes
Example: 1440 (24 hours)
downNotifyUrlMString(255)Async notification URL
Webhook URL for transaction status updates
Valid HTTP/HTTPS URL
redirectUrlOString(512)Redirect URL
URL to redirect the customer after payment
Valid HTTP/HTTPS URL
signMStringSignature
Digital signature for request authentication
See Signature

Request Body Example

Content-type: application/json

Response Body Parameters

FieldRequiredTypeDescription
successMBooleanRequest success status
true: success, false: failure
codeMStringResponse status code
9999: success; other values: failure
msgOStringResponse message
Human-readable status description
null on success
timeStampMNumberResponse timestamp
Server response time in milliseconds
dataMObjectResponse data object
Contains transaction details
orderNumMStringMerchant order number
Same as orderNum in the request
platOrderNumMStringPlatform order number
System-generated internal transaction reference
amountMNumberTransaction amount
feeMNumberFee
methodMStringPayment method (Nigeria)
As returned by the platform — see Regional Payment Guide — Nigeria
productDetailMStringProduct detail
customerNameMStringCustomer name
customerEmailMStringCustomer email
customerPhoneMStringCustomer phone
validTimeMNumberExpiry timestamp
Order expiry time in milliseconds
cashierUrlMStringCashier URL
Redirect URL for payment
Content-type: application/json

API Mode (transOrder)

The merchant specifies the payment method in the request and initiates the transaction directly with the payment channel. The response returns payData / payDataType (such as VA account number or wallet redirect link) without redirecting to the platform H5 cashier.

Request URL

EnvironmentURL
Sandboxhttps://openapi.toppayment.com/sandbox/ng/pay/transOrder
Productionhttps://openapi.toppayment.com/ng/pay/transOrder

Request Body

Compared with cashier mode, the difference is:

FieldRequiredTypeDescription
methodMString(16)Payment method (Nigeria)
Required in API mode. Examples: PAGA, PALMPAYBANK, OPAY, PALMPAY — full list: Regional Payment Guide — Nigeria

All other fields are the same as cashier mode.

Request Body Example

Content-type: application/json

Response Body Parameters

Common response fields (success, code, msg, timeStamp, and orderNum, platOrderNum, amount, fee, method, productDetail, customerName, customerEmail, customerPhone, validTime in data) are the same as cashier mode. API mode focuses on:

FieldRequiredTypeDescription
payDataMStringPayment data
VA account number, wallet redirect link, etc. — meaning depends on payDataType
payDataTypeMStringPayment data type
Values: VA, CASHIER_URL
cashierUrlOStringCashier URL
Some channels may return this as well; in API mode, use payData as the primary field

payDataType Reference

payDataTypeDescriptionTypical method
VAVirtual account — merchant guides the customer to transfer to this accountPAGA, PALMPAYBANK
CASHIER_URLUpstream payment page redirect linkOPAY, PALMPAY wallets
Content-type: application/json

Notification

Async notifications are identical for both order placement modes. Nigeria callbacks are fixed to v1.

HTTP Request

FieldRequiredTypeDescription
Content-TypeMStringHTTP request content type specification
Fixed value: application/json

Notification Body

FieldRequiredTypeDescription
platOrderNumMStringPlatform order number
System-generated internal transaction reference
versionMStringVersion
Fixed value: v1
orderNumMStringMerchant order number
Same as orderNum in the original request
amountMNumberTransaction amount
feeMNumberFee
customerNameMStringCustomer name
Payer name
customerEmailMStringCustomer email
customerPhoneMStringCustomer phone
statusMStringTransaction status
See Transaction Status Codes
signMStringSignature
Digital signature for callback verification

Response

Important

Return only the string SUCCESS to acknowledge receipt of the notification.

{
    "platOrderNum": "PRE2009165141186183168",
    "version": "v1",
    "orderNum": "NG12345621",
    "amount": 5000,
    "fee": 100,
    "customerName": "Chinedu",
    "customerEmail": "[email protected]",
    "customerPhone": "2348031234567",
    "status": "SUCCESS",
    "sign": "m5++HHEOfaVL3opFSuihVE4kkdLaCyhpFVSSLJld8WeEhlH93Ido5MQQ6peWrf+8eCkQd127jesL9esQDdFAiGKkem5BwvqTAvZGQm9v7M33Sy+W58OkGkb3/8BxQwCLTIUouhwpj1TwIeqP3JWo3AFMm5qezH3JbVfOd1IZ9Gw="
}