Paga wallet
Request payment from any of Paga’s millions of wallet holders. They approve it in the Paga app, and the money moves from their wallet to you.
| 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
Create a payment request
With your customer’s phone number or email, and paymentMethods set to ["REQUEST_MONEY"].
Paga notifies your customer
If the phone number or email belongs to a Paga wallet, your customer gets a notification in the Paga app automatically.
Send them to pay
On mobile, open AppPaymentLink so the Paga app launches straight to the payment. Elsewhere, share WebPaymentLink.
Your customer approves
They approve in the app or on the web page, then return to your redirectUrl.
Paga notifies you
A callback reaches your callback URL once the payment is approved. Verify it, then fulfil.
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/jsonSet paymentMethods to ["REQUEST_MONEY"]. Use an empty string for payer.email in the hash if you don’t send it.
{
"referenceNumber": "ORD-2026-0189",
"amount": 50,
"currency": "NGN",
"payer": {
"name": "Bello Ramon",
"phoneNumber": "08064343187"
},
"payee": { "name": "Your business name" },
"expiryDateTimeUTC": "2026-11-10T15:35:00",
"isSuppressMessages": true,
"payerCollectionFeeShare": 1,
"payeeCollectionFeeShare": 0,
"redirectUrl": "https://yourstore.com/payment/complete",
"callBackUrl": "https://yourstore.com/webhooks/paga",
"paymentMethods": ["REQUEST_MONEY"]
}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 | Phone number on your customer’s Paga wallet. Hash value 4 |
payer.email | No | Email on your customer’s Paga wallet. Hash value 5 |
payee.name | Yes | Your business name, shown in the payment request |
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 |
redirectUrl | No | Where to send your customer after they approve the payment. Also added to the app link |
callBackUrl | Yes | Where Paga sends the callback |
paymentMethods | Yes | ["REQUEST_MONEY"] |
{
"referenceNumber": "ORD-2026-0189",
"statusCode": "0",
"statusMessage": "success",
"requestAmount": 50,
"totalPaymentAmount": 50.41,
"paymentMethods": [
{
"name": "REQUEST_MONEY",
"properties": {
"WebPaymentLink": "https://justpaga.me/79A73E1A-C2D7-F111-AEAE-8EE7991AAE9D",
"AppPaymentLink": "https://smart.link/w6hy5vgnh50t6?deeplink=mypagaapp%3A%2F%2Fads%3Fid%3Drequest_money_fulfil%26externalReference%3D79A73E1A-C2D7-F111-AEAE-8EE7991AAE9D%26redirectUrl%3Dhttps%253A%252F%252Fyourstore.com%252Fpayment%252Fcomplete"
}
}
],
"expiryDateTimeUTC": "2026-11-10T15:35:00",
"isPayerPagaAccountHolder": false,
"bankName": "Paga",
"redirectUrl": "https://yourstore.com/payment/complete"
}Response fields (12)
| Field | What it’s for |
|---|---|
referenceNumber | Your reference from the request |
statusCode | 0 means the payment request was created |
statusMessage | Readable status |
requestAmount | The amount you asked for |
totalPaymentAmount | The amount your customer pays, including any fee you pass on. Show this one |
paymentMethods[].name | REQUEST_MONEY, the method you requested |
paymentMethods[].properties.AppPaymentLink | A deep link that opens the Paga app straight to the payment. Use it on mobile |
paymentMethods[].properties.WebPaymentLink | A web page where your customer can pay. Use it on desktop or if they don’t have the app |
expiryDateTimeUTC | When the request expires, in UTC |
isPayerPagaAccountHolder | true if the phone number or email belongs to a Paga wallet, so the app notification was sent |
bankName | Paga |
redirectUrl | Where your customer returns after paying, as you sent it |
No app notification? If isPayerPagaAccountHolder is false, the phone number or email isn’t on a Paga wallet, so no notification was sent. Your customer can still pay with AppPaymentLink or WebPaymentLink, or you can ask for the details on their Paga account.
2. Send your customer to pay
There are three ways your customer can reach the payment. Use the one that fits where they are:
App notification
Sent by Paga when the phone number or email belongs to a Paga wallet. Your customer approves it in the app.
App link
Open AppPaymentLink from a “Pay with Paga” button. The app launches straight to the payment.
Web link
Share WebPaymentLink by SMS or email, or open it on desktop.
Show totalPaymentAmount, not your requested amount, if your customer pays the fee.
3. Handle the callback
Paga sends a PAYMENT_COMPLETE callback to your callback URL when the customer approves. 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 your customer declines or the request expires, you get a final callback so you can close the order.
4. Check payment status
Use the status endpoint to confirm a payment if a callback hasn’t arrived, or to double-check before you fulfil a large order.
POST /status
Authorization: Basic base64(publicKey:secretKey)
hash: sha512(referenceNumber + hashKey)
Content-Type: application/json{
"referenceNumber": "ORD-2026-0189"
}Request parameters (1)
| Parameter | Required | Description |
|---|---|---|
referenceNumber | Yes | The referenceNumber you used when you created the payment request. Hash value 1 |
{
"referenceNumber": "ORD-2026-0189",
"statusCode": "0",
"statusMessage": "success",
"data": {
"referenceNumber": "ORD-2026-0189",
"statusCode": "0",
"statusMessage": "success",
"requestAmount": 50.0,
"totalPaymentAmount": 50.0,
"expiryDateTimeUTC": "2026-11-10T15:35:00",
"additionalData": {}
}
}Response fields (10)
| Field | Meaning |
|---|---|
referenceNumber | The payment request you asked about |
statusCode | 0 means your status request worked. It doesn’t tell you whether the payment was made |
statusMessage | Readable status of your status request |
data.referenceNumber | The payment request you asked about |
data.statusCode | The payment’s own status. 0 means paid. See Collect API status codes for the others |
data.statusMessage | Readable status of the payment |
data.requestAmount | The amount you asked for |
data.totalPaymentAmount | The amount your customer pays, including any fee you pass on |
data.expiryDateTimeUTC | When the payment request expires, in UTC |
data.additionalData | Extra details for some payment methods. Often empty |
Read data.statusCode, not the outer statusCode. The outer statusCode only says whether your status request worked. Fulfil the order only when data.statusCode is 0.
Don’t poll on a timer. Wait for the callback, and only check status if it hasn’t arrived. If you do check, wait a few seconds and double the wait each time, as in Best practices.
Good to know
Use the app link on mobile
Open AppPaymentLink from a button in your mobile app or site. It launches the Paga app straight to the payment, so customers don’t have to find the notification.
Share the web link as a backup
Send WebPaymentLink by SMS or email, or show it on desktop, in case the notification is missed.
Set a redirect URL
With redirectUrl, customers come back to your app or site after approving. Still confirm payment from the callback, not the redirect.
Cancel or refund
Cancel a request your customer hasn’t paid, or refund one they have. See Refunds.
Need help? We’re here 24/7
Talk to our support team any time, or ask questions in the developer community.
Updated 4 days ago