API Basics
Request Methods
For the majority of our integration options (excluding via USB and APP installation), we utilize the HTTPS request methods (POST, GET, PUT, DELETE). The specific request method required for each endpoint will be clearly indicated.
HOST URL
The base URL for accessing our API endpoints is: https://payapi.opayweb.com
Data Format
Both the request body and the response data are formatted in JSON.
Integration Support
To facilitate the integration process, we offer data samples for each endpoint and authentication samples in various popular programming languages. You can simply copy these samples and replace the placeholder parameters with your own data.
Common Parameters
Common parameters must be included in all API requests.
Request Header
| Parameter | Type | Required | Description |
| clientAuthKey | String[32] | Yes | OPay provides a unique KEY for each Business. One business account will only have one clientAuthKey. |
| version | String[20] | Yes | Current version: V1.0.1 |
| bodyFormat | String[20] | Yes | Format of request body before encryption: JSON. |
| timestamp | String[15] | Yes | The timestamp is the number of milliseconds since January 1, 1970 (midnight UTC/GMT). The validity period is 5 minutes. |
Request Body
| Parameter | Type | Required | Description |
| paramContent | String[BIG] | Yes | Encrypted JSON |
| sign | String[64] | Yes | Splice a timestamp to the paramContent to get the signature |
{
"paramContent": "gkFFz97z1sEbbOeVPdoR+cHkf4Ib........",
"sign": "ORDVpacVCNW0yiSviNeow......"
}
2
3
4
Request
| Parameter | Type | Required | Description |
| code | String[4] | Yes | 00000 means response successful, otherwise failed |
| message | String[512] | Yes | |
| sign | String[64] | Yes | Signature of message authentication returned by OPay |
| timestamp | String[15] | Yes | Time Stamp |
| data | String[BIG] | Yes | The response to the encrypted JSON string. You must decrypt the "data" to obtain the parameters in plaintext. |
{
"code": "00000",
"message": "SUCCESSFUL",
"sign":"yUJrerHr9GqKP7y......",
"timestamp":"1283203360637",
"data":"KshnV6Y4kfAXUvwPNb......"
}
2
3
4
5
6
7
{
"code": "00000",
"message": "SUCCESSFUL",
"sign":"yUJrerHr9GqKP7y......",
"timestamp":"1283203360637",
"data": {
"param1": "XXXXXXX",
"param2": "XXXXXXX"
}
}
2
3
4
5
6
7
8
9
10
Webhooks
Webhook URL Configuration
To enable this feature, please add your webhook URL on your OPay Business Dashboard using the Super Admin role. Please ensure that your webhook URL is publicly accessible and can receive incoming requests. OPay Business Dashboard > "Integration" Menu > "Developer Tools" page > POS & Others > Add Webhook URL
Response Time
The standard response time for webhooks is set at 5 seconds. If your system requires more time to process long-running tasks, we strongly advise you to send an acknowledgement of receipt to us before proceeding with your own tasks.
Failure and Resend Policy
If we do not receive a timely response, we will consider the webhook attempt as failed. In such cases, we will automatically retry sending the webhook after 5 seconds. Between every 5 subsequent attempts, the interval between retries will increase.
Transaction Status
| Status | Description |
| SUCCESS | Payment is successful and the money is credited to your dedicated account. |
| FAIL | Payment is failed and the money is not with OPay. |
| CLOSE | Payment is closed due to timeout. |
| CANCEL | Payment is cancelled by the operator. |
| PENDING | Awaiting payment from customers. This status only occurs when you call the endpoint to query transaction status. |
Common Response Codes
| Response Code | Description |
| 00000 | Response successful. |
| 00004 | Invalid request parameters. Please check your common request header & body parameters. |
| 00005 | Duplicate business order number for initiating transactions, please check again. |
| 10000 | System busy, please try again. |
| 11004 | Response blocked due to system error, please try again later. |
| 11005 | Response data is null due to system error, please try again later. |
| A_1001 | Request expired. Please try again. |
| C1004 | Invalid request as the recipientBankCode is null. |
| C1009 | The bank code is not supported, please check your bank code. |
| C_1111 | Fail to query merchant key. Please reconfirm you have submitted the key or try again later. |
