TN Integration API

This page provides the APIs for querying the TN bound to an OPay POS and querying successful TN transactions.

These endpoints use the common encrypted request and response envelope described in API Basics. The request parameters below are the plaintext JSON after decryption, and the response parameters are the plaintext JSON inside data after decryption.

Query TN by POS SN

URL: https://payapi.opayweb.com/openApi/tn/queryBySn

This endpoint queries the TN bound to a specified POS serial number under the specified merchant.

Request Parameters

{
  "headMerchantId": "256622040884147",
  "merchantId": "256622040884148",
  "sn": "POS-SN-001"
}

Response Parameters

{
  "headMerchantId": "256622040884147",
  "merchantId": "256622040884148",
  "sn": "POS-SN-001",
  "tn": "6123456789",
  "tnStatus": "ACTIVE",
  "recipientName": null,
  "receiptBank": "OPay",
  "boundTime": "Aug 26,2026 11:00:00",
  "updatedTime": "Aug 26,2026 11:01:00"
}

Query TN Transaction Records

URL: https://payapi.opayweb.com/openApi/tn/queryTransactionRecords

This endpoint queries successful inbound transactions for the specified merchant, TN, POS serial number and date range.

Special Notes

• headMerchantId, merchantId, tn, sn, startTime, endTime, pageNum and pageSize are required.
• startTime and endTime use Nigeria date format yyyyMMdd, for example 20260902.
• The date range is inclusive and must not exceed 7 calendar days. To query all transactions on September 2, 2026, pass both startTime and endTime as 20260902.
• tn is an OPay dedicated TN. The recommended format is 10 digits beginning with 6, for example 6123456789.
• status currently supports only SUCCESS; the gateway always queries successful transactions.
• merchantId is queried exactly as provided. The endpoint does not query all authorized merchants under the group, which prevents cross-merchant data exposure.
• If tn or sn is non-empty but does not match any transaction, the endpoint returns a successful response with an empty records list and total equal to 0.

Request Parameters

{
  "headMerchantId": "256622040884147",
  "merchantId": "256622040884148",
  "tn": "6123456789",
  "sn": "POS-SN-001",
  "startTime": "20260902",
  "endTime": "20260902",
  "status": "SUCCESS",
  "pageNum": 1,
  "pageSize": 50
}

Response Parameters

Parameter	Type	Description
records	Array	Transaction records.
records[].payNo	String	OPay payment order number.
records[].orderNo	String	Original order number.
records[].outOrderNo	String	Merchant order number.
records[].headMerchantId	String	Your OPay Business ID.
records[].merchantId	String	Your OPay Branch ID.
records[].sn	String	POS serial number.
records[].tn	String	OPay dedicated TN, recommended as 10 digits beginning with 6.
records[].status	String	Transaction status. The current query returns SUCCESS transactions.
records[].amount	String	Transaction amount in Naira.

Show more parameters

{
  "records": [
    {
      "payNo": "202609021234567890",
      "orderNo": "202609021234567891",
      "outOrderNo": "MERCHANT-ORDER-001",
      "headMerchantId": "256622040884147",
      "merchantId": "256622040884148",
      "sn": "POS-SN-001",
      "tn": "6123456789",
      "status": "SUCCESS",
      "amount": "100.00",
      "currency": "NGN",
      "senderName": "John",
      "senderBank": "OPay",
      "senderAccount": "********9012",
      "recipientName": null,
      "receiptBank": "OPay",
      "receiptAccount": "6123456789",
      "remark": null,
      "transactionTime": "Sep 02,2026 14:30:00",
      "completedTime": "Sep 02,2026 14:31:00",
      "rrn": "RRN001"
    }
  ],
  "total": 1,
  "pageNum": 1,
  "pageSize": 50,
  "hasMore": false
}

Error Scenarios

Common Response Codes

For the encrypted response envelope, see API Basics. The TN endpoints use the following codes in addition to the common API codes: