Bill payment

All the value-added services you need in one place

We support a long list of biller in Nigeria and you could earn a commission from us when you vend for your customers. Please see the list of biller supported and the applicable commission you can potentially earn anytime you vend for your customer.

📘

Billers

These are merchants whose services you can purchase on Paga. Customers are able to renew subscription for DSTV, recharge their pre-paid meter for Eko Electric, or register for JAMB, etc, on the platform.

To get started making bill payments on Paga, you’ll need to ensure your Paga account is funded for each bill payment operation you’re about to perform.

Step for making bill payment:

👍

Demo

Let’s demo the steps below for making bill payment for DSTV:

Step 1: Fetch the billers list

You’ll need to fetch the list of the available biller to get their names and respective identifiers (UUID).

See sample request below

referenceNumber: A unique reference number provided by the business, identifying the operation. hashIndex-1

POST /paga-webservices/business-rest/secured/getMerchants HTTP/1.1
Host: mypaga.com
Content-Type: application/json
principal: 93A5E317-738220032-94DE-50BA4B653EE5
credentials: fS4*tfgyhjklokk+QvTq%WE
hash:  69cdcaaee22e0491d83602e8ab15ebb2a70c3657803af0bd7e786cf529c5f9a210f1a5bfdefa2d3bbcbc786b1b65a5b29a65acfdea8b062fc91f3f689db41640
Content-Length: 39

{ 
    "referenceNumber": "123457679"
}

Sample Response

{
    "responseCode": 0,
    "responseCategoryCode": null,
    "message": "Success",
    "referenceNumber": "614129479891",
    "merchants": [
                {
            "name": "DStv",
            "uuid": "A3878DC1-F07D-48E7-AA59-8276C3C26647",
            "displayName": "DStv",
            "description": "null"
        },
        {
            "name": "African Cable Television",
            "uuid": "04f384d5-0b8e-4d21-bff4-a441ca44c6f1",
            "displayName": "ACTV",
            "description": "null"
        },...
        {
            "name": "Abuja Electricity Distribution Company",
            "uuid": "13B5041B-7143-46B1-9A88-F355AD7EA1EC",
            "displayName": "aedc",
            "description": "null"
        }
]

}

Step 2: Fetch biller services

You should identify the biller you want to vend and proceed to fetch the list of services or products for the merchants. For this demo, we are assuming you want to fetch the list of services available for DSTV

Sample Request:

referenceNumber: A unique reference number provided by the business, identifying the operation. - hashIndex-1
MerchantPublicId: The merchant UUID fetched from the Get Merchant call in step 1 above - hashIndex-2

POST /paga-webservices/business-rest/secured/getMerchantServices HTTP/1.1
Host: mypaga.com
Content-Type: application/json
principal: 93A5E317-738220032-94DE-50BA4B653EE5
credentials: fS4*tfgyhjklokk+QvTq%WE
hash:  69cdcafgh22e0491d83602e8ab15ebb2a70c3657803af0bd7e786cf529c5f9a210f1a5bfdefa2d3bbcbc786b1b65a5b29a65acfdea8b062fc91f3f689db41640
Content-Length: 104

{
    "referenceNumber": "45701411444",
    "merchantPublicId": "A3878DC1-F07D-48E7-AA59-8276C3C26647"
}

Sample Response:

services.name: Name of the services as identified by the biller
services.code: The code name for the biller services, this will be used in subsequent job in step 3 and 4 below to identify the services
services.price: The applicable prices for the services, this will be used in subsequent
service.shortCode: This code identify the services but won’t be needed in subsequent requests.

{
    "responseCode": 0,
    "responseCategoryCode": null,
    "message": "Success",
    "referenceNumber": "295976555265",
    "services": [
        {
            "name": "ACCESS",
            "code": "ACCACC101",
            "price": 1500.0,
            "shortCode": "ACC"
        },
        {
            "name": "FAMILY",
            "code": "FAMFAM102",
            "price": 3000.0,
            "shortCode": "FAM"
        },
        {
            "name": "MINI",
            "code": "MINMIN115",
            "price": 5000.0,
            "shortCode": "MIN"
        },
        {
            "name": "PREMIUM",
            "code": "PREPRE130",
            "price": 15000.0,
            "shortCode": "PRE"
        },
        {
            "name": "GERMAN ONLY",
            "code": "GERGER101",
            "price": 30000.0,
            "shortCode": "GER"
        }
]
}

Step 3: Validate the customer reference

For bill pay transactions, customers often provides their primary identifier with the biller to identify their payment and receive value from the biller. For DSTV payment, customer provides their smartcard number and before making payment you’ll need to validate the smartcard number and return customer information where applicable.

Sample Request:

referenceNumber: A unique reference number provided by the business, identifying the transaction. - HashIndex-1
merchantAccount: The merchant UUID fetched from the Get Merchant call in step 1 above - Hashindex-2
merchantReferenceNumber: This should contain the reference number provided by the customer, in the case of DSTV, the Merchant reference number will be the smartcard number - Hashindex-3
merchantServiceProductCode: This should be the service.code generated from Step 2 response above - Hashindex-4

POST /paga-webservices/business-rest/secured/getMerchantAccountDetails HTTP/1.1
Host: mypaga.com
Content-Type: application/json
principal: 93A5E317-738220032-94DE-50BA4B653EE5
credentials: fS4*tfgyhjklokk+QvTq%WE
hash:  69cdcafgh22e0491d83602e8ab15ebb2a70c3657803af0bd7e786cf529c5f9a210f1a5bfdefa2d3bbcbc786b1b65a5b29a65acfdea8b062fc91f3f689db41640
Content-Length: 133

{
    "referenceNumber": "ref_133435",
    "merchantAccount": "A3878DC1-F07D-48E7-AA59-8276C3C26647",
    "merchantReferenceNumber": "4115702261",
    "merchantServiceProductCode": "DSBONPC"
}

Sample Response

{
    "responseCode": 0,
    "responseCategoryCode": null,
    "message": "Success",
    "customerName": "E OBIANOZIE",
    "phoneNumber": null,
    "accountNumber": null,
    "address": null,
    "details": {
        "customerName": "E OBIANOZIE",
        "details": "E OBIANOZIE"
    }
}

Step 4: Make Bill payment

After successfully validating the customers reference number, you’re ready to make payment to the biller. To continue our previous demo, we are making payment to DSTV for Access package and we’ve identified the biller UUID and service code for DSTV Access

Where applicable (Electricity), the token will be returned and you can parse that to the customer or merchant automatically give the customer value for the purchase e.g PayTv purchases

referenceNumber: A unique reference number provided by the business, identifying the transaction. - HashIndex-1
Amount - The amount due on the service you're purchasing - Hashindex-2
currency - NGN for Nigeria-based merchants
merchantAccount: The merchant UUID fetched from the Get Merchant call in step 1 above - Hashindex-3
merchantReferenceNumber: This should contain the reference number provided by the customer, in the case of DSTV, the Merchant reference number will be the smartcard number - Hashindex-4
merchantServiceProductCode: This should be the service.code generated from Step 2 response above

POST /paga-webservices/business-rest/secured/merchantPayment HTTP/1.1
Host: mypaga.com
Content-Type: application/json
principal: 93A5E317-738220032-94DE-50BA4B653EE5
credentials: fS4*tfgyhjklokk+QvTq%WE
hash:  69cdcafgh22e0491d83602e8ab15ebb2a70c3657803af0bd7e786cf529c5f9a210f1a5bfdefa2d3bbcbc786b1b65a5b29a65acfdea8b062fc91f3f689db41640
Content-Length: 234

{
    "referenceNumber": "45345987850439260",
    "amount": "900",
    "currency": "NGN",
    "merchantAccount": "A3878DC1-F07D-48E7-AA59-8276C3C26647",
    "merchantReferenceNumber": "4115702261",
    "merchantService": ["DSBONPC"]
}

Sample Response

{
    "responseCode": 0,
    "responseCategoryCode": null,
    "message": "You have successfully paid N 900.00 to DStv for acct 4115702261. Merchant Confirmation: 151127150. Paga TxnID: 7P7T6",
    "referenceNumber": "45345987850439260",
    "merchantTransactionReference": "151127150",
    "transactionId": "7P7T6",
    "currency": "NGN",
    "exchangeRate": null,
    "fee": 0.00,
    "integrationStatus": "SUCCESSFUL"
}

How about token?

For billers that return a token response in their purchase, the merchant payment response will be slightly different from what was returned in step-4 above. The response sample will include additional properties parameters.

{
    "responseCode": 0,
    "responseCategoryCode": null,
    "message": "You have successfully paid N 900.00 to DStv for acct 4115702261. Merchant Confirmation: 151127150. Paga TxnID: 7P7T6",
    "referenceNumber": "45345987850439260",
    "merchantTransactionReference": "151127150",
    "transactionId": "7P7T6",
    "currency": "NGN",
    "exchangeRate": null,
    "fee": 0.00,
    "integrationStatus": "SUCCESSFUL"  
    "additionalProperties": {
        "unitType": "",
        "totalPayment": "",
        "debtBefore": "",
        "customerAccountNumber": "",
        "units": "",
        "debtPayment": "",
        "paymentDate": "",
        "meterSerial": "",
        "customerName": "",
        "receiptNumber": "",
        "vat":"",
        "token": "457689867542345677087687564"
    }
}

Check Transaction Status

Billpay operation is a synchronous operation and we've successfully made your purchase, however, we advise all integrators to reconfirm their purchase. This is a best practice all partners are encouraged to adhere to always

referenceNumber: A unique reference number provided by the business, identifying the transaction. - HashIndex-1

POST /paga-webservices/business-rest/secured/transactionStatus HTTP/1.1
Host: mypaga.com
Content-Type: application/json
principal: 93A5E317-738220032-94DE-50BA4B653EE5
credentials: fS4*tfgyhjklokk+QvTq%WE
hash:  69cdcaaee22e0491d83602e8ab15ebb2a70c3657803af0bd7e786cf529c5f9a210f1a5bfdefa2d3bbcbc786b1b65a5b29a65acfdea8b062fc91f3f689db41640
Content-Length: 39

{ 
    "referenceNumber": "45345987850439260"
}

Sample Response

{
    "responseCode": 0,
    "responseCategoryCode": null,
    "message": null,
    "referenceNumber": "45345987850439260",
    "currency": "NGN",
    "status": "SUCCESSFUL",
    "transactionReference": "BP_20220611123013576_3857203_7P7T6_jl9bk",
    "transactionId": "7P7T6",
    "transactionType": "BILL_PAY",
    "dateUTC": 1654947013577,
    "amount": 900.0,
    "merchantTransactionReference": "151127150",
    "exchangeRate": null,
    "fee": 0.00,
    "integrationStatus": "SUCCESS",
    "additionalProperties": {}
}

What’s Next