Pay with USSD

This endpoint allows you get short USSD codes for a transaction using the transactionReference of an initialized transaction and the bank code of the customer’s bank from the get banks endpoint. This is useful if you want to control the payment interface. There are a lot of UX considerations to keep in mind if you choose to do this so we recommend you read this.

This endpoint is protected with OAuth 2.0 Bearer token. To find out more about authorization for Monnify endpoints, check Here

Endpoint URL: {{base_url}}/api/v1/merchant/ussd/initialize

HTTP Method: POST

The {{base_url}} for test is https://sandbox.monnify.com but when you go live, it changes to the live url

To get the USSD code of the desired bank, you simply need to pass the transaction reference to the endpoint above and also the desired bank code.

Pay with with USSD Request

{
    "transactionReference":"MNFY|57|20220824191001|413442",
    "bankUssdCode":"737"
}

Pay with USSD Code Response

{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "responseCode": "00",
        "responseDescription": "Success",
        "ussdCode": "3617",
        "paymentCode": "*737*000*3617#",
        "providerReference": "22082492407553903617",
        "authorizedAmount": 20.00,
        "transactionReference": "MNFY|57|20220824191001|413442"
    }
}

Sample Error Response

{
    "requestSuccessful": false,
    "responseMessage": "Could not find transaction with the specified transaction reference",
    "responseCode": "99"
}

The above error response is returned when a wrong transaction reference is used to generate a USSD code.

Field Reference

^(M) indicates fields that are mandatory in the request body. ^(m) Indicates fields that are mandatory only if the parent object is not empty.

Field	Description

Field	Description
^{transactionReference(M)}	Unique reference generated for the transaction by Monnify.
^bankCode(M)	Bank code of the desired bank from which payment would be made.
^{authorizedAmount}	The amount to be paid by the customer.
ussdCode	The generated code for that bank.
providerReference	The reference of the provider of the ussd code.
paymentCode	The ussd string the user is to dial on this device for payment.