Bank USSD

Environment	Base URL
Sandbox	`https://beta-collect.paga.com`
Live	`https://collect.paga.com`

Authenticate with HTTP Basic and a hash header, as in Authentication.

How it works

1. Create a payment request

POST /paymentRequest
Authorization: Basic base64(publicKey:secretKey)
hash: sha512(referenceNumber + amount + currency + payer.phoneNumber + payer.email + hashKey)
Content-Type: application/json

Set paymentMethods to ["FUNDING_USSD"]. Use an empty string for payer.email in the hash if you don’t send it.

{
  "referenceNumber": "ORD-2026-0188",
  "amount": 200,
  "currency": "NGN",
  "payer": {
    "name": "Bello Ramon",
    "phoneNumber": "08064343187",
    "bankId": "43F4DED6-78EC-4047-AD34-BAB75E679EB7"
  },
  "payee": { "name": "Your business name" },
  "expiryDateTimeUTC": "2026-11-10T16:35:00",
  "isSuppressMessages": true,
  "payerCollectionFeeShare": 1,
  "payeeCollectionFeeShare": 0,
  "callBackUrl": "https://yourstore.com/webhooks/paga",
  "paymentMethods": ["FUNDING_USSD"]
}

All request parameters (14)

Parameter	Required	Description
`referenceNumber`	Yes	Your unique reference. Use it to match callbacks and check status. Hash value 1
`amount`	Yes	Amount to request, in naira. Hash value 2
`currency`	Yes	`NGN`. Hash value 3
`payer.name`	Yes	Customer’s name
`payer.phoneNumber`	Yes	Customer’s phone number. Hash value 4
`payer.email`	No	Customer’s email address. Hash value 5
`payer.bankId`	Yes	Your customer’s bank, from Get Banks
`payee.name`	Yes	Your business name
`payerCollectionFeeShare`	Yes	Share of the fee your customer pays, from `0.0` to `1.0`
`payeeCollectionFeeShare`	Yes	Share of the fee you pay. Both shares must add up to 1.0
`expiryDateTimeUTC`	No	When the request expires, in UTC, up to one week ahead
`isSuppressMessages`	No	`true` stops Paga emailing or texting your customer. Default `false`
`callBackUrl`	Yes	Where Paga sends the callback
`paymentMethods`	Yes	`["FUNDING_USSD"]`

{
  "referenceNumber": "ORD-2026-0188",
  "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": "2026-11-10T16:35:00",
  "isPayerPagaAccountHolder": true
}

Response fields you’ll use most (3)

Field	What it’s for
`paymentMethods[].properties.USSDShortCode`	The code your customer dials
`paymentMethods[].properties.PaymentReference`	Paga’s reference for the USSD payment
`totalPaymentAmount`	The amount your customer pays, including any fee you pass on

2. Show your customer the USSD code

Display the code with the bank name and amount, and tell your customer to dial it from the phone number registered with that bank:


Dial	*`894000724+40554208#`**
Bank	First Bank
Amount	₦200.00

3. Handle the callback

Paga sends a PAYMENT_COMPLETE callback to your callback URL when the customer approves the payment. The callback, its fields and the hash check are the same as for Dynamic virtual accounts.

Hash: notificationId + statusCode + externalReferenceNumber + state + outstandingBalance + hashKey, with SHA-512.
Respond with HTTP 200. Paga retries up to three times with the same notificationId.
If the code expires unused, you get a final callback so you can close the order.

4. Check payment status

Call POST /status with your referenceNumber. The hash is sha512(referenceNumber + hashKey), and the payment’s status is in data.statusCode.