Bank USSD

One-time use Bank USSD for payment

Bank USSD allows you to generate a unique USSD code from any commercial bank in Nigeria and accept instant payment when your customer dial the USSD code and authorises it with their 4 digit pin.

📘

What's Bank USSD

Each bank has its own USSD code e.g Paga - *242# | GTBank - *737# | Access Bank - *901# etc. With Bank USSD, you're able to generate a unique USSD code such as *737*000*235647# for a GTbank customer to make a payment, you can do similar for all other commercial banks

How to get paid

Generate a bank USSD and get paid in 3 simple steps:

  • Generate bank USSD
  • Display the USSD code to your customer to dial and authenticate
  • Wait for a callback after successful payment, we will send you a callback with details of the payment

Step 1: Get all the needed information

Below is the list of parameters required to generate account number

Argument

Data Type

Description

Required

referenceNumber

String

A unique reference number representing this request. The same reference number will be returned in the response and can be used to query the payment request status

True

amount

Float

The amount being requested

True

currency

String

The currency of the operation, only required if being executed in a foreign currency.

True

payer

Object

The person/entity from whom we are requesting a payment

True

payer.name

String

Name of the payer.

True

payer.phoneNumber

String

Phone number of the payer. Either one of phone-number or e-mail address must be provided

True

payer.email

String

E-mail address of the payer. Either one of phone-number or e-mail address must be provided

False

payer.bankId

String

UUID representing the payer’s bank. Available from the getBanks endpoint request.

True

payee

Object

The person/entity to receive the payment, if the payee identifier (eg. phone number, email, etc.) is not supplied, the payment request processor is automatically selected as recipient

True

payee.name

String

Name of the recipient
It would be important to note that the name that shows up for the Payer (eg. when doing a name enquiry at a bank), is what you provide in the payee.name parameter by default.

True

expiryDateTimeUTC

String

Time limit for the payment request to be fulfilled otherwise it will be automatically expired, this must be with one week of requesting payment. If not provided the default expiry window value is applied.

False

isSuppressMessages

Boolean

Suppress direct email messaging to payer. Default value is false

False

payerCollectionFeeShare

Float

This represents the percentage of the payment request fee that will be charged to the payer. The combination of payerCollectionFeeShare and recipientCollectionFeeShare must be less than 1.0

True

payeeCollectionFeeShare

Float

This represents the percentage of the payment request fee that will be charged to the payee. The combination of payerCollectionFeeShare and payeeCollectionFeeShare must be less than 1.0

True

callBackUrl

String

The callback url that will be notified with updates on the payment request status

False

paymentMethods

List

List of permitted payment methods for processing this request. Parse value as FUNDING_USSD

True

Step 2: Generate a Bank USSD

For this step, you’ll need to parse all the param above in a POST request to obtain the payment bank USSD Code

POST /paymentRequest HTTP/1.1
Host: beta-collect.paga.com
hash:  1bb6d8140b6e4979db506c866f8608b48db01bd38cd3c8e64597d6ed8510eeecc8b6fb4a9c6f3f999fe43ad92aee2f80418c2bcb95faa5d68dcde00cf0e19aa1
Authorization: Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ==
Content-Type: application/json
Content-Length: 589

{
    "referenceNumber": "27565600679759",
    "amount": 200,
    "currency": "NGN",
    "payer": {
        "name": "Ramon Mustapha",
        "phoneNumber": "08064343187",
        "bankId":"43F4DED6-78EC-4047-AD34-BAB75E679EB7"
    },
    "payee": {
        "name": "Lagos One"
    },
    "expiryDateTimeUTC": "2022-06-05T23:00:00",
    "isSuppressMessages": false,
    "payerCollectionFeeShare": 0.0,
    "payeeCollectionFeeShare": 1.0,
    "callBackUrl": "https://webhook.site/efda4728-139e-4efa-b5c3-d7fb24e28475",
    "paymentMethods": [
        "FUNDING_USSD"
    ]
}

Sample Response

{
    "referenceNumber": "27565600679759",
    "statusCode": "0",
    "statusMessage": "success",
    "requestAmount": 200.0,
    "totalPaymentAmount": 200.0,
    "currency": "NGN",
    "paymentMethods": [
        {
            "name": "FUNDING_USSD",
            "properties": {
                "USSDShortCode": "*894*000*724+40554208#",
                "PaymentReference": "40554208"
            }
        }
    ],
    "expiryDateTimeUTC": "2022-06-05T23:00:00",
    "isPayerPagaAccountHolder": true
}

Step 3: Display the Bank USSD to your customer to make payment

Display the Bank USSD to your customers on a friendly UI

Bank USSD: *894*000*724+40554208#
Bank: First Bank
Amount: 200.00

Step 4: Callback Notification for successful payment

After your customer makes the payment, we’ll send a callback notification to the callback URL you provided in your request

{
  "event": "PAYMENT_COMPLETE",
  "notificationId": "a12ef82b-14d0-4a67-a08c-162b95154f59",
  "statusCode": "0",
  "statusMessage": "Payment Request has been authorized",
  "externalReferenceNumber": "27565600679759",
  "state": "CONSUMED",
  "outstandingBalance": 0,
  "paymentAmount": 200.00,
  "cumulativePaymentAmount": 200.00,
  "collectionFee": 1.5,
  "fundingDetails": {
    "payerAccountNumber": "0980763085",
    "paymentReferenceNumber": null,
    "payerName": "Bello Mustapha",
    "payerBankName": null,
    "payerBankAccountNumber": "0980763085"
  },
  "hash": "33f9c9bd0785c2ccfa66ddedfbae7c3b56361250c581a39edad1d2ed08ccfbed845f34b8c30532f7c0ec544483ebee9360c5749bfe5eaa9986ac5553488e058a"
}

Step 5: Check payment status

You’ll need to make a server to server call to get the status of transaction. Your JSON request should look like below

POST /status HTTP/1.1
Host: beta-collect.paga.com
hash:  6c6a222fea30d4881db29d14445779be27d841508f0accfe9ba1d97d23159981597fdf1e4be4efae564102e6b949e5e8ee7af3e73fd4268297001119c5512906
Authorization: Basic e3t1c2VybmFtZX19Ont7cGFzc3dvcmR9fQ==
Content-Type: application/json
Content-Length: 44

{
  "referenceNumber" : "27565600679759"
}

You’ll receive a JSON response like below, the data dictionary will give you the details and status of your request.

{
    "referenceNumber": "27565600679759",
    "statusCode": "0",
    "statusMessage": "success",
    "data": {
        "referenceNumber": "27565600679759",
        "statusCode": "0",
        "statusMessage": "success",
        "requestAmount": 200.0,
        "totalPaymentAmount": 200.0,
        "currency": "NGN",
        "paymentMethods": [
            {
                "name": "FUNDING_USSD",
                "properties": {
                    "USSDShortCode": "*894*000*724+*894*000*724+40554208##",
                    "PaymentReference": "*894*000*724+40554208#"
                }
            }
        ],
        "expiryDateTimeUTC": "2022-06-05T23:00:00",
        "isPayerPagaAccountHolder": true
    }
}

What if payment wasn’t made or completed

Don’t worry, we will send you conclusive callback once the request expires and the customer didn’t make payment.

We are done!


What’s Next