Ussd payments

This page describes how to accept offline payments from customers using USSD

Flutterwave allows you to collect payments from your customers offline using USSD. With USSD payments, you call our APIs to create a charge, then give your customer instructions to complete the payment on her/his mobile phone. Once payment is completed we notify you on your webhook.

Let us show you how to accept payments using USSD.

Pre-requisites for accepting USSD payments.

1. Sign-up for an account here .

2. Set up a webhook to get notified on payments, to see more on webhooks visit our Webhook section

3. When trying to accept payment on a website you can use our Flutterwave inline method and pass currency as NGN and type as ussd, once you do this, the payment options for USSD will be enabled on your checkout page. Note that you also have to enable this payment method on your dashboard.

4. If you would prefer to accept payments using our APIs please see how to [accept USSD payments via APIs](ref: charge-via-mpesa).

5. After getting a response for the transaction, call the Transaction verification endpoint to confirm the final status of the transaction.

📘

Available Banks

At the moment, banks available for USSD payments (and their numeric codes) are:

1. Access Bank -- 044
2. Ecobank -- 050
3. Fidelity Bank -- 070
4. First Bank of Nigeria -- 011
5. First City Monument Bank (FCMB) -- 214
6. GTBank -- 058
7. Heritage Bank -- 030
8. Keystone Bank -- 082
9. Stanbic IBTC Bank -- 221
10. Sterling Bank -- 232
11. Union Bank -- 032
12. United Bank for Africa -- 033
13. Unity Bank -- 215
14. VFD Microfinance Bank -- 090110
15. Wema Bank -- 035
16. Zenith Bank -- 057

Step 1 - Initiate payment

Send your payload to our charge endpoint: https://api.flutterwave.com/v3/charges?type=ussd

Method: POST

JSON

{
        "tx_ref": "MC-15852309v5050e8y",
        "account_bank": "057",
        "amount": "1500",
        "currency": "NGN",
        "email": "[email protected]",
        "phone_number": "054709929220",
        "fullname": "John Madakin"

}

Parameter Definition

Parameter	Required	Description
tx_ref	True	This is a transaction reference you supply to identify different transactions on your account. It is important to ensure that you pass unique references for every transaction.
account_bank	True	This is the Bank numeric code e.g 058
amount	True	This is the amount to be charged. It is passed in NGN - ('amount':'1500').
currency	True	This is the specified currency to charge in. (expected value: NGN)
email	True	This is the email address of the customer.
phone_number	True	This is the phone number linked to the customer's mobile money account.
client_ip	False	Internet Protocol. This represents the current IP address of the customer carrying out the transaction.
device_fingerprint	False	This is the fingerprint for the device being used. It can be generated using a library on whatever platform is being used.
meta	False	This is an object you can use to include any additional payment information you would like to associate with this charge
fullname	False	Should include first and last name of the customer

Payment Response

When you send your payload to our charge endpoint to make a payment, you'll get a successful response if it all goes well.

JSON

{
    "status": "success",
    "message": "Charge initiated",
    "data": {
        "id": 2382777,
        "tx_ref": "MC-15852309v5050e8y",
        "flw_ref": "WKOM430901627909006960",
        "device_fingerprint": "N/A",
        "amount": 1500,
        "charged_amount": 1500,
        "app_fee": 481.5,
        "merchant_fee": 0,
        "processor_response": "Transaction in progress",
        "auth_model": "USSD",
        "currency": "NGN",
        "ip": "::ffff:127.0.0.1",
        "narration": "Flutterwave Developers",
        "status": "pending",
        "payment_type": "ussd",
        "fraud_status": "ok",
        "charge_type": "normal",
        "created_at": "2021-08-02T12:56:45.000Z",
        "account_id": 20937,
        "customer": {
            "id": 1355534,
            "phone_number": "054709929220",
            "name": "John Madakin",
            "email": "[email protected]",
            "created_at": "2021-08-02T12:56:45.000Z"
        },
        "payment_code": "3650"
    },
    "meta": {
        "authorization": {
            "mode": "ussd",
            "note": "*889*767*3650#"
        }
    }
}

What happens after I call the charge endpoint?

When you call the charge endpoint you would receive the JSON response above with a note field that contains the USSD code for your customer to dial to complete their payment. Then we call your webhook once the transaction has been completed with a successful response.

🚧

Note

• Developers are expected to display the code returned as meta.authorization.note to their users. This code once dialled starts the USSD session on the user's mobile device.

• For Guaranty trust bank, after your customer dials the USSD code, they are required to specify the payment code as shared in response.

Verify payment

After charging a customer successfully, you need to verify that the payment was successful with Flutterwave before giving value to your customer on your website.

Check our Transaction verification section for implementation instructions