Pay-In · Nigeria
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:
| Mode | Path | Description |
|---|---|---|
| Cashier mode | /pay/prePay | Default mode. Returns cashierUrl for redirecting the customer to the platform H5 cashier to complete payment |
| API mode | /pay/transOrder | Specify 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:
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP 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.
| Environment | URL |
|---|---|
| Sandbox | https://openapi.toppayment.com/sandbox/ng/pay/prePay |
| Production | https://openapi.toppayment.com/ng/pay/prePay |
Request Body
| Field | Required | Type | Description |
|---|---|---|---|
| mchNo | M | String(32) | Merchant number Unique merchant identifier assigned by the platform Used for merchant authentication and transaction routing |
| orderNum | M | String(64) | Merchant order number Unique transaction identifier Format: Alphanumeric string Used for transaction tracking and reference |
| amount | M | Number(32,8) | Transaction amount Numeric type Currency is Naira (NGN). Decimals are not allowed for Nigeria — pass an integer Example: 5000 |
| productDetail | M | String(100) | Product detail Transaction purpose or description UTF-8 string |
| method | O | String(16) | Payment method (Nigeria) Optional; if omitted, the customer selects on the cashier. Examples: PAGA, PALMPAYBANK, OPAY, PALMPAY — full list: Regional Payment Guide — Nigeria |
| timestamp | M | String(13) | Timestamp Request timestamp in milliseconds Example: 1749451858772 |
| customerName | M | String(64) | Customer name Payer name UTF-8 string |
| customerEmail | M | String(64) | Customer email Payer email address Valid email format |
| customerPhone | M | String(32) | Mobile number Format: 234 followed by a 10-digit mobile number whose first digit is 7, 8, or 9Example: 2348031234567 |
| expiryPeriod | O | Number(1–9999) | Expiry period Order validity in minutes Example: 1440 (24 hours) |
| downNotifyUrl | M | String(255) | Async notification URL Webhook URL for transaction status updates Valid HTTP/HTTPS URL |
| redirectUrl | O | String(512) | Redirect URL URL to redirect the customer after payment Valid HTTP/HTTPS URL |
| sign | M | String | Signature Digital signature for request authentication See Signature |
Request Body Example
Content-type: application/json
{
"mchNo": "{{mchNo}}",
"orderNum": "NG1234561",
"amount": 5000,
"productDetail": "Product",
"method": "PALMPAY",
"timestamp": "1749451858772",
"customerName": "Chinedu",
"customerEmail": "[email protected]",
"customerPhone": "2348031234567",
"expiryPeriod": 1440,
"downNotifyUrl": "https://example.com/notify",
"redirectUrl": "https://example.com/return",
"sign": "Generate per signature rules and replace"
}
Response Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| success | M | Boolean | Request success status true: success, false: failure |
| code | M | String | Response status code 9999: success; other values: failure |
| msg | O | String | Response message Human-readable status description null on success |
| timeStamp | M | Number | Response timestamp Server response time in milliseconds |
| data | M | Object | Response data object Contains transaction details |
| orderNum | M | String | Merchant order number Same as orderNum in the request |
| platOrderNum | M | String | Platform order number System-generated internal transaction reference |
| amount | M | Number | Transaction amount |
| fee | M | Number | Fee |
| method | M | String | Payment method (Nigeria) As returned by the platform — see Regional Payment Guide — Nigeria |
| productDetail | M | String | Product detail |
| customerName | M | String | Customer name |
| customerEmail | M | String | Customer email |
| customerPhone | M | String | Customer phone |
| validTime | M | Number | Expiry timestamp Order expiry time in milliseconds |
| cashierUrl | M | String | Cashier URL Redirect URL for payment |
Content-type: application/json
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "NG1234561",
"platOrderNum": "PRE2009093829059153920",
"amount": 5000,
"fee": 100.0,
"method": "PALMPAY",
"productDetail": "Product",
"customerName": "Chinedu",
"customerEmail": "[email protected]",
"customerPhone": "2348031234567",
"validTime": 1767926672819,
"cashierUrl": "https://example.cashier/pay"
}
}
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
| Environment | URL |
|---|---|
| Sandbox | https://openapi.toppayment.com/sandbox/ng/pay/transOrder |
| Production | https://openapi.toppayment.com/ng/pay/transOrder |
Request Body
Compared with cashier mode, the difference is:
| Field | Required | Type | Description |
|---|---|---|---|
| method | M | String(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
{
"mchNo": "{{mchNo}}",
"orderNum": "NGAPI1234561",
"amount": 5000,
"productDetail": "Product",
"method": "PAGA",
"timestamp": "1749451858772",
"customerName": "Chinedu",
"customerEmail": "[email protected]",
"customerPhone": "2348031234567",
"expiryPeriod": 1440,
"downNotifyUrl": "https://example.com/notify",
"sign": "Generate per signature rules and replace"
}
{
"mchNo": "{{mchNo}}",
"orderNum": "NGAPI7890121",
"amount": 5000,
"productDetail": "Product",
"method": "PALMPAY",
"timestamp": "1749451858772",
"customerName": "Chinedu",
"customerEmail": "[email protected]",
"customerPhone": "2348031234567",
"expiryPeriod": 1440,
"downNotifyUrl": "https://example.com/notify",
"sign": "Generate per signature rules and replace"
}
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:
| Field | Required | Type | Description |
|---|---|---|---|
| payData | M | String | Payment data VA account number, wallet redirect link, etc. — meaning depends on payDataType |
| payDataType | M | String | Payment data type Values: VA, CASHIER_URL |
| cashierUrl | O | String | Cashier URL Some channels may return this as well; in API mode, use payData as the primary field |
payDataType Reference
| payDataType | Description | Typical method |
|---|---|---|
VA | Virtual account — merchant guides the customer to transfer to this account | PAGA, PALMPAYBANK |
CASHIER_URL | Upstream payment page redirect link | OPAY, PALMPAY wallets |
Content-type: application/json
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "NGAPI1234561",
"platOrderNum": "PRE2009093829059153920",
"amount": 5000,
"fee": 100.0,
"method": "PAGA",
"productDetail": "Product",
"customerName": "Chinedu",
"customerEmail": "[email protected]",
"customerPhone": "2348031234567",
"validTime": 1767926672819,
"payData": "1234567890",
"payDataType": "VA"
}
}
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "NGAPI7890121",
"platOrderNum": "PRE2009093829059153921",
"amount": 5000,
"fee": 100.0,
"method": "PALMPAY",
"productDetail": "Product",
"customerName": "Chinedu",
"customerEmail": "[email protected]",
"customerPhone": "2348031234567",
"validTime": 1767926672819,
"payData": "https://example.cashier/palmpay/pay",
"payDataType": "CASHIER_URL"
}
}
Notification
Async notifications are identical for both order placement modes. Nigeria callbacks are fixed to v1.
HTTP Request
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP request content type specification Fixed value: application/json |
Notification Body
| Field | Required | Type | Description |
|---|---|---|---|
| platOrderNum | M | String | Platform order number System-generated internal transaction reference |
| version | M | String | Version Fixed value: v1 |
| orderNum | M | String | Merchant order number Same as orderNum in the original request |
| amount | M | Number | Transaction amount |
| fee | M | Number | Fee |
| customerName | M | String | Customer name Payer name |
| customerEmail | M | String | Customer email |
| customerPhone | M | String | Customer phone |
| status | M | String | Transaction status See Transaction Status Codes |
| sign | M | String | Signature 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="
}
SUCCESS
