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:

  1. Fidelity Bank (070)
  2. Guaranty Trust Bank (058)
  3. Keystone Bank (082)
  4. Sterling Bank (232)
  5. United Bank for Africa (033)
  6. Unity Bank (215)
  7. 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

ParameterDescription
Content-typeapplication/JSON
MerchantIdOPay 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.
AuthorizationBearer + 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 PROPERTYDESCRIPTION
referenceOrder number of merchant (unique order number from merchant platform)
productDescProduct description, utf-8 encoded
userPhoneUser phone number sent by merchant
userRequestIpThe IP address requested by user, need pass-through by merchant, user Anti-phishing verification.
amountAmount in kobo
currencyCurrency charge should be performed in. Default is NGN
callbackUrlThe asynchronous callback address after transaction successful.
expireAtTransaction would be closed within specific time. Value is in minute.
bankCodeMake 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 PROPERTYDESCRIPTION
referenceOrder number of merchant (unique order number from merchant platform)
orderNoOrder number of OPay payment
amountAmount in kobo
currencyCurrency charge should be performed in. Default is NGN
statusINITIAL
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

ParameterDescription
Content-typeapplication/JSON
MerchantIdOPay 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.
AuthorizationBearer + 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"
}
PROPERTYDESCRIPTION
referenceOrder number of merchant (unique order number from merchant platform)
orderNoOrder number of OPay payment
amountAmount in kobo
currencyCurrency charge should be performed in. Default is NGN
statusINITIAL
PENDING
SUCCESS
FAIL
CLOSE

CONTENTS

  • Community

  • Official Website
  • Facebook
  • Linkedln
  • Twitter
Was this page helpful?
Yes
No

Help us make this page better

Please leave a comment on how we can improve your experience.