USSD Payments
This API allows you to accept offline payments via USSD.
Please note that there are only certain banks that support this form of payment. Below are the banks and their numeric codes:
- Fidelity Bank (070)
- Guaranty Trust Bank (058)
- Keystone Bank (082)
- Sterling Bank (232)
- United Bank for Africa (033)
- Unity Bank (215)
- Zenith Bank (057)
Step 1: Initialize a ussd transaction
Here you can commence a bank transfer transaction by making a POST request to the /transaction/ussd/initialize endpoint.
HTTP Method
POST
Sandbox
http://sandbox-cashierapi.opayweb.com/api/v3
Production
https://cashierapi.opayweb.com/api/v3
Header Parameters
| Parameter | Description |
|---|---|
| Content-type | application/JSON |
| MerchantId | OPay merchant ID is a unique 15-digit number assigned to all OPay merchants. To get your merchantID, login to your OPay Dashboard and click on Settings. |
| Authorization | Bearer + Signature (Signature is a combination of both the payload and your secret/private key) |
API Endpoint
/transaction/ussd/initialize
Sample Request
post/transaction/ussd/initialize
curl -X POST --header 'Authorization: Bearer Signature' --header 'MerchantId:
256619092316009' --header 'content-type: application/json'
https://cashierapi.opayweb.com/api/v3/transaction/ussd/initialize
Sample Request Body
post/transaction/ussd/initialize
{
"reference": "test_20191123132233",
"productDesc": "The best wireless earphone in history",
"userPhone": "+2349876543210",
"userRequestIp": "123.123.123.123",
"amount": "100",
"currency": "NGN",
"callbackUrl": "https://you.domain.com/callbackUrl",
"expireAt": "10",
"bankCode": "070"
}| REQUEST PROPERTY | DESCRIPTION |
|---|---|
| reference | Order number of merchant (unique order number from merchant platform) |
| productDesc | Product description, utf-8 encoded |
| userPhone | User phone number sent by merchant |
| userRequestIp | The IP address requested by user, need pass-through by merchant, user Anti-phishing verification. |
| amount | Amount in kobo |
| currency | Currency charge should be performed in. Default is NGN |
| callbackUrl | The asynchronous callback address after transaction successful. |
| expireAt | Transaction would be closed within specific time. Value is in minute. |
| bankCode | Make a transaction with a bank account uusd. (070 -- Fidelity Bank, 058 -- Guaranty Trust Bank, 082 -- Keystone Bank, 232 -- Sterling Bank, 033 -- United Bank for Africa, 215 -- Unity Bank, 057 -- Zenith Bank) |
Sample Response
{
"reference": "test_20191123132233",
"orderNo": "20019212912901281821982",
"amount": "100",
"currency": "NGN",
"status": "INITIAL",
"ussdDialCode": "*966*6*7297*507607#"
}| RESPONSE PROPERTY | DESCRIPTION |
|---|---|
| reference | Order number of merchant (unique order number from merchant platform) |
| orderNo | Order number of OPay payment |
| amount | Amount in kobo |
| currency | Currency charge should be performed in. Default is NGN |
| status | INITIAL PENDING SUCCESS FAIL CLOSE |
| ussdDialCode | *966*6*7297*507607# |
Step 2: Get status of USSD transactions
When you’ve initialized a transaction, you should wait 10 seconds or more then proceed to check the status of the transaction.
Keep requerying in 10 seconds or more intervals to get the final status of your transaction, which is either “FAILED” or “SUCCESSFUL”.
Please note that the Authorization header consists of “Bearer Signature”, which is essentially a HMAC SHA512 signature of the whole payload signed using your Secret Key. The payload should be in alphabetical order. You can use our Signature calculator here.
HTTP Method
POST
Sandbox
http://sandbox-cashierapi.opayweb.com/api/v3
Production
https://cashierapi.opayweb.com/api/v3
Header Parameters
| Parameter | Description |
|---|---|
| Content-type | application/JSON |
| MerchantId | OPay merchant ID is a unique 15-digit number assigned to all OPay merchants. To get your merchantID, login to your OPay Dashboard and click on Settings. |
| Authorization | Bearer + Signature (Signature is a combination of both the payload and your secret/private key) |
API Endpoint
/transaction/ussd/status
Sample Request
post/transaction/ussd/status
curl -X POST --header 'Authorization: Bearer Signature' --header 'MerchantId:
256619092316009' --header 'content-type: application/json'
https://cashierapi.opayweb.com/api/transaction/ussd/status
Sample Request Body
post/transaction/ussd/status
{
"reference": "test_20191123132233",
"orderNo": "20019212912901281821982"
}Sample Response
{
"reference": "test_20191123132233",
"orderNo": "20019212912901281821982",
"amount": "100",
"currency": "NGN",
"status": "INITIAL"
}| PROPERTY | DESCRIPTION |
|---|---|
| reference | Order number of merchant (unique order number from merchant platform) |
| orderNo | Order number of OPay payment |
| amount | Amount in kobo |
| currency | Currency charge should be performed in. Default is NGN |
| status | INITIAL PENDING SUCCESS FAIL CLOSE |