Bank USSD Payment
Initialize a USSD transaction.
OPay Bank USSD Payment
For calling the API using the POST method you can use these endpoints URL:
In case you are still in the developing phase, use the following staging API endpoint URL
https://testapi.opaycheckout.com/api/v1/international/payment/create
Once you are ready for production, you should use the following production API endpoint URL instead
https://liveapi.opaycheckout.com/api/v1/international/payment/create
Request Parameters:
- Header: Authorization(API Calls Signature), MerchantId
- Json object containing the transaction information:
HTTP POST parameters
Here is a detailed description for the parameters you need to complete the POST request:
An example call of Bank USSD Payment API is as follows :
Header must contain the "Signature" , "MerchantId"
Signature is calculated using SHA-512 HMAC signed with your Private Key. See API Calls Signature section for more details.
Bank USSD Payment Response
Response Parameters:
The parameters contained in the response received whenever you call the Transaction Create API as a JSON Object.
Here is a detailed description for the parameters received in the response:
Parameter | type | Description | example | |
---|---|---|---|---|
reference | String |
Unique merchant payment order number. | 937102167 | |
orderNo | String |
Unique Opay payment order number. | 211004140885521681 | |
status | enum |
[INITIAL, PENDING, SUCCESS, FAIL, CLOSE] | SUCCESS | |
amount | ||||
currency | String |
Currency | NGN | |
total | Long |
amount(cent unit). | 400 | |
vat | ||||
currency | String |
Currency | NGN | |
total | Long |
amount(cent unit). | 10 | |
nextAction | ||||
actionType | String |
Next action type | SHOW_USSD | |
USSD | String |
USSD | "*919*000*2103#" | |
failureCode | String |
fail error code. | payment fail error code, not blank when status [FAIL/CLOSE] | |
failureReason | String |
fail error message. | payment fail error message, not blank when status [FAIL/CLOSE] |
Error Handling
After submitting an API call to OPay, you receive a response back to inform you that
your request was received and processed. A successful OPay API should return a status code 00
,
meanwhile, in a situation where any payment processing error occurred, you will receive an error code with a
message to describe the reason of the error. A sample error response can be found below.
Depending on the HTTP status code of the response, you should build some logic to handle any errors that a request or the system may return. A list of possible potential error codes that you may receive can be found below.
Error Code | Error Message |
---|---|
02000 | authentication failed. |
02001 | request params not valid. |
02003 | payMethod not support. |
02004 | the payment reference already exists. |
02002 | merchant not configured with this function. |
02007 | merchant not available. |
50003 | service not available, please try again. |