Opay and Palmpay (NGN)

54pay offers collections in Nigeria which enables customers with OPay and Palmpay wallets to seamlessly complete payments to merchants, providing users with a fast and secure checkout experience.

Base URLs

Environment	Base Url
Development	https://subsidiary.dev.mypaygate.co
Production	https://subsidiary.prod.mypaygate.co

Request Headers

Header Name	Value Format	Description
Content-Type	application/json	Specifies the request body format. Must always be application/json.
x-module	Base_64(amount+transactionReference+customerNumber)	Base64-encoded concatenation of the transaction amount, transaction reference, and customer number.
x-business	Base64(MerchantPublicKey)	Base64-encoded merchant public key used to identify and authenticate the merchant.
x-app	api	Application identifier. Use the literal value api for all API-initiated requests

OPay Collection (NGN)

54Pay offers collections using OPay, which enables customers with an OPay Wallet to seamlessly complete payments to merchants, providing users with a fast and secure checkout experience.

POST https://subsidiary.dev.mypaygate.co/collection/v1/payin

Sample Request

curl --location 'https://subsidiary.dev.mypaygate.co/collection/v1/payin' --header 'x-Business: UEstNi03MDYyM2JhZDAxMzM0NzQ0LUlTMkEyMGst...' --header 'x-module: NTAwQURGMDAyNDQzNDU0NTM1MDA4MTI1OTI1NzY0OQ==' --header 'X-app: api' --header 'Content-Type: application/json' --data-raw '{
  "requestHeader": {
      "clientId": "",
      "requestType": "C"
  },
  "customerName": "Test Payments",
  "customerEmail": "test@gmail.com",
  "customerNumber": "8160009000",
  "transactionReference": "ADF002443454535008",
  "transactionDescription": "collection",
  "transactionAmount": "100",
  "transactionCurrency": "NGN",
  "transactionCountry": "NG",
  "successUrl": "https://54Pay.co",
  "errorUrl": "https://54Pay.co",
  "cancelUrl": "https://54Pay.co",
  "operatorCode": "NGOPY",
  "webhookUrl": ""
}'

Request Body Parameters

Parameter	Data Type	Required	Description
requestHeader.clientId	String	No	-
requestHeader.requestType	String	Yes	Request type indicator
customerName	String	Yes	Full name of the customer initiating the payment.
customerEmail	String	Yes	Email address of the customer.
customerNumber	String	Yes	Customer’s registered Opay/Palmpay Number. Also used in computing the x-module header.
transactionReference	String	Yes	Merchant-generated unique reference for the transaction. Must be unique per request. Also used in computing the x-module header.
transactionDescription	String	Yes	Short description or purpose of the transaction (e.g., "collection", "payment for invoice #001").
transactionAmount	String	Yes	Amount to be collected, expressed as a numeric string (e.g., "500"). Also used in computing the x-module header.
transactionCurrency	String	Yes	ISO 4217 currency code. For Nigerian collections, this must be "NGN".
transactionCountry	String	Yes	ISO 3166-1 alpha-2 country code. For Nigeria, this must be "NG".
operatorCode	String	Yes	Operator Code
successUrl	String	Yes	URL to redirect the customer upon a successful payment.
errorUrl	String	Yes	URL to redirect the customer when a payment error occurs.
cancelUrl	String	No	URL to redirect the customer if they cancel the payment flow.
webhookUrl	String	No	Webhooks will be sent to the dashboard configured collection webhookUrl by default unless otherwise included in the request.

Sample Response

Successful Response (HTTP 200)

{
  "responseDetails": {
      "responseCode": "09",
      "responseMessage": "PENDING",
      "statusDescription": "Payment to be completed on checkout UI"
  },
  "processorReference": "PG-C-177455058542246",
  "transactionReference": "TXN16987099",
  "redirectionRequired": true,
  "redirectionUrl": "https://express.opaycheckout.com/apiCashier/redirect/payment/checkoutHome?orderToken=TOKEN.2eb6b6fc-f4d4-4351-88b8-f01f05a9ee63"
}

note

OPay payment links are only valid for 30 minutes.

Response Fields

Field	Type	Description
responseDetails.responseCode	String	Status code of the request. "09" indicates a pending state awaiting customer action on the checkout UI.
responseDetails.responseMessage	String	Human-readable status. "PENDING" means the transaction has been initiated and is awaiting completion.
responseDetails.statusDescription	String	Plain-language explanation of the current transaction status.
processorReference	String	54Pay's internal reference for this transaction.
transactionReference	String	Merchant-supplied transactionReference.
redirectionRequired	Boolean	Indicates whether the customer must be redirected to complete payment.
redirectionUrl	String	The checkout URL to which the customer must be redirected to complete payment.

PalmPay Collection (NGN)

54Pay offers collections using PalmPay, which enables customers with a PalmPay Wallet to seamlessly complete payments to merchants.

POST https://subsidiary.dev.mypaygate.co/collection/v1/payin

Sample Request

curl --location 'https://subsidiary.dev.mypaygate.co/collection/v1/payin' --header 'x-Business: <Base64(MerchantPublicKey)>' --header 'x-module: <Base64(amount+transactionReference+customerNumber)>' --header 'X-app: api' --header 'Content-Type: application/json' --data-raw '{
  "requestHeader": {
      "clientId": "",
      "requestType": "C"
  },
  "customerName": "Test Payments",
  "customerEmail": "test@gmail.com",
  "customerNumber": "8160009000",
  "transactionReference": "ADF002443454535009",
  "transactionDescription": "collection",
  "transactionAmount": "100",
  "transactionCurrency": "NGN",
  "transactionCountry": "NG",
  "successUrl": "https://54Pay.co",
  "errorUrl": "https://54Pay.co",
  "cancelUrl": "https://54Pay.co",
  "operatorCode": "NGPPY",
  "webhookUrl": ""
}'

Sample Response

Successful Response (HTTP 200)

{
  "responseDetails": {
      "responseCode": "09",
      "responseMessage": "PENDING",
      "statusDescription": "Payment to be completed on checkout UI"
  },
  "processorReference": "PG-C-177455064285059",
  "transactionReference": "TXN18447565",
  "redirectionRequired": true,
  "redirectionUrl": "https://checkout.palmpay.com/h5-checkout/?countryCode=NG&tntCode=PALMPAY&payToken=c0ec7ba2-ba02-4beb-84d7-f277fc40b20e&orderNo=24260317131031775173&businessProductType=pay_wallet&businessMode=three_mode&identityType=NEW&callable=..."
}

note

PalmPay payment links are only valid for 30 minutes.

Response Fields

Field	Type	Description
responseDetails.responseCode	String	"09" indicates a pending state. The transaction has been created and the customer must complete payment via the PalmPay checkout.
responseDetails.responseMessage	String	"PENDING" — the transaction is awaiting customer action on the PalmPay hosted checkout page.
responseDetails.statusDescription	String	Plain-language description of the transaction status.
processorReference	String	54Pay's internal reference for this transaction. Use for reconciliation and support queries.
transactionReference	String	Merchant-supplied transactionReference
redirectionRequired	Boolean	Always true for PalmPay collections. The customer must be redirected to the PalmPay hosted checkout to complete payment.
redirectionUrl	String	The PalmPay hosted checkout URL. Redirect the customer to this URL to complete the payment.

Sample Webhooks

54Pay sends an asynchronous HTTP POST notification to your configured webhookUrl when the payment status changes. Ensure your endpoint is accessible and returns a 200 OK response to acknowledge receipt.

Successful

{
"transaction_reference": "PG-C-176060158983729",
"transaction_status": "Funds Received",
"transaction_fee": 0,
"amount_received": 500,
"initiated_date": "2025-10-16 09:00:08",
"current_status_date": "2025-10-16 09:00:13",
"received_from": {},
"merchant_reference": "TXN083G26DSG6",
"status": "COMPLETED",
"channel": "BANK_ACCOUNT",
"currency_code": "NGN"
}