Become a biller
Put your products in front of Paga’s 20 million+ users. List as a biller, and customers can pay you from the Paga app, at Paga agents and POS terminals, and through the partner platforms that use Paga, with the money in your Paga business account in real time.
This API works the other way round. You build a small set of endpoints on your server, and Paga calls them. Paga uses them to check your customers and tell you about each payment.
Where your customers can pay
How it works
Build your endpoints
Implement submitTransaction, and validateCustomer if you want Paga to check customers before they pay.
Get enabled
Save your base URL, username and password in the business portal, then contact the support team. Once they’ve confirmed your use case, they enable you on Paga’s channels.
Your customer pays
On any Paga channel. Paga checks the customer with you first, if you support validation.
You’re paid and notified
The money is credited to your Paga business account in real time. Paga calls submitTransaction, and you record the payment and reply with a confirmation code for your customer.
Endpoints you build
You build two endpoints on your server. Paga calls them; you don’t call Paga.
| Endpoint | Needed? | What Paga uses it for |
|---|---|---|
submitTransaction | Required | To tell you about each payment and get your confirmation |
validateCustomer | Optional | To check a customer exists and is in good standing before they pay |
Rules for every endpoint
| Rule | Detail |
|---|---|
| Address | Each endpoint lives at your base URL plus its name, such as https://your-api.example.com/submitTransaction |
| Method | POST, with a JSON body, and JSON in your response |
| Authentication | HTTP Basic, with a username and password you choose and save in the business portal |
| Response time | Reply within 1 second. If you don’t, Paga retries up to 3 times within 5 seconds |
isTest | Every request includes isTest. When it’s true, treat the call as a test: don’t affect live customers or records |
status | Every response includes a status. See Status values |
Status values
Every response you send must include one of these in status
Paga reads it to decide what happened. Send the value exactly as shown: uppercase, with the underscore.
It worked
You processed the request: you recorded the payment, or checked the customer.
The request was wrong
Something in Paga’s request was invalid or missing, such as an unknown account number format.
Your system failed
Something went wrong on your side. Add your own code in merchantStatus or a message to explain.
| Value | Meaning | Add to the response |
|---|---|---|
SUCCESS | The request was processed successfully | For submitTransaction, your confirmationCode |
CLIENT_ERROR | The request failed because of invalid parameters or other information in it | A message saying what was wrong |
SERVER_ERROR | The request failed because of an error on your system | Your merchantStatus code and a message |
Return SUCCESS only once the payment is safely recorded. For a repeat of a payment you’ve already processed, return SUCCESS again with your original response.
1. validateCustomer
Optional. Before a customer pays, Paga asks you whether they’re a real customer in good standing. Return their name so they can confirm it’s their account.
POST https://your-api.example.com/validateCustomer
Authorization: Basic base64(username:password)
Content-Type: application/json
Accept: application/json{
"isTest": true,
"customerAccountNumber": "1234567",
"customerFirstName": "",
"customerLastName": ""
}{
"status": "SUCCESS",
"message": "Customer found",
"isValid": true,
"firstName": "John",
"lastName": "Doe",
"accountStatus": "ACTIVE",
"lastPaymentDate": "2026-10-01T00:00:00Z",
"paymentDueDate": "2026-11-30T00:00:00Z",
"isDisplayed": true
}Request and response fields
| Field | Meaning |
|---|---|
customerAccountNumber | Request. The customer’s account or reference number with you |
customerFirstName, customerLastName | Request. The customer’s name, if the channel collected it |
status | SUCCESS, CLIENT_ERROR or SERVER_ERROR |
isValid | The answer Paga needs. true if this is a valid customer |
firstName, lastName | The customer’s name, shown to them to confirm |
accountStatus | ACTIVE or INACTIVE |
lastPaymentDate, paymentDueDate | Optional dates, as ISO 8601 |
isDisplayed | true lets Paga show these details to the customer |
message | Optional message |
2. submitTransaction
Required. Paga calls this for every payment to you. Record the payment, deliver the product or credit the customer’s account, and reply with the result.
POST https://your-api.example.com/submitTransaction
Authorization: Basic base64(username:password)
Content-Type: application/json
Accept: application/json{
"isTest": true,
"transaction": {
"pagaTransactionId": "XBFJX",
"merchantTransactionId": "BP-C_2018061315273249_1448479_XBFJX",
"utcTransactionDateTime": "2026-11-06T15:27:32",
"transactionType": "BILL_PAY",
"totalAmount": 500,
"merchantAmount": 492.5,
"currency": "NGN",
"isCredit": true,
"customerReference": "70000587",
"customerFirstName": "Bello",
"customerLastName": "Ramon",
"customerPhoneNumber": "+2348177777087",
"channel": "ONLINE",
"description": "Gold plan renewal",
"services": [
{ "name": "GOLD PLAN", "price": 500, "shortCode": "GP", "isPublic": true }
]
}
}Transaction fields (14)
| Field | Meaning |
|---|---|
merchantTransactionId | The idempotency key. Paga’s unique reference for the payment. Use it to recognise a payment you’ve already processed |
pagaTransactionId | Paga’s short ID for the payment, shared with everyone involved |
utcTransactionDateTime | When the customer paid, in UTC |
transactionType | BILL_PAY |
totalAmount | What the customer paid |
merchantAmount | What you receive after fees |
currency | NGN |
isCredit | true for payments |
customerReference | The customer’s account or reference number with you |
customerFirstName, customerLastName | The customer’s name |
customerPhoneNumber | The customer’s phone number |
channel | Where they paid: ONLINE, USSD, SMS, VOICE, EMAIL or E_WIDGET |
description | A description of the payment |
services | The products the customer paid for |
{
"status": "SUCCESS",
"uniqueTransactionId": "172a56a0-3dde-4837-986b-bc8965b1d35f",
"customerReference": "70000587",
"merchantStatus": "1000",
"message": "Successfully executed payment",
"confirmationCode": "XHSUR-23724-FSR4"
}Response fields (6)
| Field | Meaning |
|---|---|
status | Required. SUCCESS if you recorded the payment, CLIENT_ERROR if the request was invalid, or SERVER_ERROR if your system failed |
confirmationCode | A code Paga gives your customer as proof of payment, such as a token or receipt number |
uniqueTransactionId | Your ID for the payment |
customerReference | The customer you credited |
merchantStatus | Your own status code, if you have one |
message | A result message |
Reply within 1 second, and handle repeatsPaga expects your reply within 1 second. If it doesn’t get one, it retries up to 3 times within 5 seconds, so the same payment can reach you more than once. Use
merchantTransactionIdas your idempotency key: if you’ve seen it before, return your original response without crediting the customer again.
When you get the money. Payments are credited to your Paga business account in real time, as the customer pays. You don’t need to wait for a settlement run.
Going live
Build and test your endpoints
Make sure every endpoint honours isTest.
Save your settings
Save your base URL, username and password in the business portal.
Contact the support team
Once your integration is done, email [email protected] with your use case and the products customers will pay for. The team reviews your use case and tests your endpoints with you.
Get enabled on Paga’s channels
Once your use case is confirmed, support enables you as a biller, and customers can start paying you.
Good to know
Use merchantTransactionId to avoid duplicates
Paga may call you up to 4 times for one payment. Return the original result for a repeat instead of crediting the customer twice.
Return a useful confirmation code
Your confirmationCode is what the customer gets as proof of payment. Make it something your support team can look up.
Changing your products?
Contact the support team to add, change or remove the products customers can pay you for.
Treat test calls as tests
Calls with isTest set to true must never change live customer records.
Need help? We’re here 24/7
Talk to our support team any time, or ask questions in the developer community.
Updated about 20 hours ago