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 Bank USSD

How to get paid

Step 1: Get all the needed information

Step 2: Generate a Bank USSD

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

Step 4: Callback Notification for successful payment

Step 5: Check payment status

What if payment wasn’t made or completed

📘
What's Bank USSD