POS Integration (API)

This integration establishes a seamless and wireless connection between your system and the OPay POS. It streamlines the payment collection process to eliminate human errors, reduce the turnaround time, and ensure a smooth reconciliation experience by synchronizing payment results in real-time.

PosServer

Create Payment Order

URL: https://payapi.opayweb.com/openApi/order/checkout/createOrder

Request

Parameter	Type	Required	Description
headMerchantId	String	Yes	Your OPay Business ID
merchantId	String	Yes	Your OPay Branch ID
outOrderNo	String	Yes	Your business order number
amount	Object	Yes	Order amount, in Naira
currency	String	Yes	NGN
orderExpireTime	Long	Yes	Order expiry time, in seconds
sceneEnum	String	Yes	Please use Cash_API
subSceneEnum	String	Yes	Please contact OPay to get this value.
sn	String	Yes	POS Serial Number
isSplit	String	Yes	Split settlement? Y stands for YES; N stands for NO.

Show more parameters

POST

{
  "headMerchantId":"256622040884147",
  "merchantId":"256622040884147",
  "outOrderNo":"2334345345345211",
  "amount":"100",
  "currency":"NGN",
  "orderExpireTime":180,
  "isSplit":"N",
  "splitInfo":null,
  "productInfo":{
      "filmName":"film name",
      "filmTitle":"ticket title",
      "filmTicketNum":"film ticker number",
      "seatNum":"Seat number(multiple seats, concatenate)",
      "filmTicketAmount":"1",
      "filmFeeAmount":"1",
      "filmDate":"movie date yyyy-MM-dd",
      "filmTime":"movie showtime, hh:mm"
  }
  "remark":"XX",
  "sceneEnum":"CASH_API",
  "subSceneEnum":"FILM",
  "sn":"XXXX"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Response

Parameter	Sample Value	Type	Description
orderNo	20220704741380171865833472	String	OPay payment order number

Response Demo

{
  "code": "00000",
  "message": "SUCCESSFUL",
  "sign": "yUJrerHr9GqKP7y......",
  "timestamp": "1283203360637",
  "data": {
    "orderNo": "20220704741380171865833472"
  }
}

1
2
3
4
5
6
7
8
9

Webhook (Payment Notification)

Please submit your Webhook URL using the Super Admin role on your OPay Business Dashboard > Developer Tool page > "POS & Others" section. OPay will use this URL to send you requests to synchronize payment statuses.

Request Header

Parameter	Type	Required	Description
Content-Type	String	Yes	-
X-Opay-Tranid	String	Yes	Transaction order/No.
merchantId	String	Yes	Branch ID

Request Body

Parameter	Type	Required	Description
clientAuthKey	String	Yes	One unique KEY for each merchant. You can get it from your OPay Business Dashboard > Developer Tools.
version	String	Yes	Current version: V1.0.1
bodyFormat	String	Yes	JSON.
timestamp	String	Yes	The timestamp is the number of milliseconds since January 1, 1970 (midnight UTC/GMT). The validity period is 5 minutes.
paramContent	String	Yes
sign	String	Yes

Request Demo

{
  "clientAuthKey": "b819c755d80b4c268f831f0cef69a22e",
  "version": "V1.0.1",
  "bodyFormat": "JSON",
  "timestamp": "1283203360637",
  "paramContent": "gkFFz97z1sEbbOeVPdoR+cHkf4Ib........",
  "sign": "ORDVpacVCNW0yiSviNeow......"
}

1
2
3
4
5
6
7
8

Request Parameters

Here are the data you will get from OPay's payment notification:

Parameter	Type	Required	Description
outOrderNo	String	Yes	Your business order number
orderNo	String	Yes	OPay payment order number
status	String	Yes	Payment status
currency	String	Yes	NGN
amount	String	Yes	Your Payment amount, in Naira
fee	String	Yes	Transaction fee, in Naira
feePattern	String	Yes
senderName	String	Yes	Sender's name
senderAccount	String	Yes	Sender's account number
recipientName	String	Yes	Recipient's name

Show more parameters

Request Demo

{
  "data": {
    "outOrderNo": "220617145660907314088",
    "orderNo": "20220319702512368471543808",
    "status": "SUCCESS",
    "currency": "NGN",
    "amount": "100.00",
    "fee": "10.00",
    "feePattern": "IN_DEDUCT",
    "senderName": "Alice",
    "senderAccount": "23234324*****23423",
    "recipientName": "Michael",
    "recipientAccount": "+2345656567878",
    "transactionTime": "1692773950143",
    "completedTime": "1692773950143",
    "transactionType": "apiCheckout",
    "transactionName": "API CheckOut",
    "payType": "POS",
    "sn": "XXXXX",
    "remark": "test"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Response

Here are the data you will get from OPay's payment notification:

Parameter	Sample	Type	Description
code	00000	String	Response successful
message	SUCCESSFUL	String

Response Demo

{
  "code": "00000",
  "message": "SUCCESSFUL"
}

1
2
3
4

Query Order Details

URL: https://payapi.opayweb.com/openApi/order/checkout/qryOrderDetail

Request

Parameter	Type	Required	Description
headMerchantId	String	Yes	Your OPay Business ID
merchantId	String	Yes	Your OPay Branch ID
outOrderNo	String	Optional	Your business order number. You should pass either outOrderNo or orderNo.
orderNo	String	Optional	OPay payment order number. You should pass either outOrderNo or orderNo.

POST

{
  "headMerchantId": "256622040884147",
  "merchantId": "256622040884147",
  "outOrderNo": "2334345345345211",
  "orderNo": "20220704741380171865833472"
}

1
2
3
4
5
6

Response

Parameter	Type	Description
code	String	Response successful
message	String
sign	String
timestamp
data	Object
outOrderNo	String	Your business order number
orderNo	String	OPay payment order number
payNo	String	OPay payment serial number
headMerchantId	String	Your Business ID
merchantId	String	Your Branch ID

Show more parameters

Response Demo

{
  "code": "00000",
  "message": "SUCCESSFUL",
  "sign": "yUJrerHr9GqKP7y......",
  "timestamp": "1283203360637",
  "data": {
    "outOrderNo": "2334345345345211",
    "orderNo": "20220704741380171865833472",
    "payNo": "2334345345345245",
    "headMerchantId": "256622022480363",
    "merchantId": "256622022480364",
    "status": "SUCCESS",
    "senderName": "Alice",
    "senderAccount": "23234324*****23423",
    "recipientName": "Michael",
    "recipientAccount": "+2345656567878",
    "amount": "100.00",
    "fee": "10.00",
    "feePattern": "OUT_DEDUCT",
    "currency": "NGN",
    "transactionTime": "1692773950143",
    "completedTime": "1692773950143",
    "transactionType": "apiCheckout",
    "transactionName": "API CheckOut",
    "payType": "POS",
    "sn": "XXXX",
    "remark": null
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

← Authentication POS Integration (USB) →