Welcome to the Getting started page, this page will provide you with the information required to get started with Paga Merchant Services
1. Overview
This document will guide you in implementing the Paga RESTful Merchant Services API. Which you can use to execute the different Paga services exposed to Merchants. This API works for both JSON and XML determined by the HTTP request Accept header value.
2. PAGA Merchant API
The PAGA Merchant API platform exposes operations that are useful for Merchants to provide PAGA’s services to themselves or third-party clients. The Paga Merchant Services are:
- Get Transaction Details
This service allows the merchant to verify the status and details of an executed transaction using the pre-shared transaction reference number. - Get Transaction Details By Invoice Number
This service allows the merchant to verify the status and details of the executed transaction using the invoice number. - Get Process Details
This service allows the merchant to verify the status and details of an executed process. - Reconciliation Report
This service allows the merchant to get any settlement reconciliation items generated for payments intended for the merchant made through the platform. - Get Foreign Exchange Rate
This service allows a merchant to get foreign exchange rates between two currencies. - Refund Bill Pay
This service method allows a merchant to refund Bill Pay transaction made to Paga by a customer.
3. Paga Authentication Details
As of this time, Paga Merchant authentication details have to be obtained directly from Paga. That will change in the near future.
The steps required to obtain authentication details are outlined below.
- Create a Paga Business account
- Send and email to the Paga Operations Support team.
- You will be contacted by a Paga representative that will provide you with the information you require.
4. Implementations
Get Transaction Details
This service allows the merchant to verify the status and details of an executed process or to determine if a transaction was indeed executed on the system using the pre-shared transaction reference number. The transaction reference number used is unique across the platform, so merchant aggregators checking for transaction status across multiple users should use this method.
Request parameters
Argument Name | Type | Requirement | Description |
|---|---|---|---|
referenceNumber | String | Required | The unique transaction code returned as part of a previously executed transaction |
Sample Request
URL:
https://www.mypaga.com/paga-webservices/merchant-rest/secured/getTransactionDetails
Http Headers:
principal: publicId (merchant business publicId)
credentials: p@ssword1
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber+ apikey)
Content-Type: application/json
Request Body:
{"referenceNumber":"242355"}
Note
Please note that the hash parameter must contain the values of those params mentioned in the same order and the Api key (the key given by paga) hashed with SHS-512 algorithm. Excluding the + sign 
Response Parameters
Argument Name | Type | Requirement | Description |
|---|---|---|---|
referenceNumber | String | Required | The unique reference number code provided with the request |
status | String | optional | The status of the transaction, if the transaction was found on the system. Note that any status other than UKNOWN means that the transaction was found on the system |
merchantReference | String | optional | The executing customer's reference number on the merchant's system as provided by the customer during transaction processing (eg. customer account number, invoice number etc.) |
dateTimeUTC | dateTime | optional | The transaction date and time provided in UTC standard time |
transactionType | String | optional | An enum representing the type of transaction executed |
amount | Double | optional | The case amount of the transaction. Note that this may be different from the amount remitted to the biller or actually charged to the customer depending on any fees included in the transaction. |
transactionId | String | optional | The common transaction id shared with all parties involved in the transaction |
channel | String | optional | The channel on which the transaction was executed |
byAgent | Boolean | optional | Whether the transaction was executed at an agent (true) or not (false) |
currency | String | optional | The currency used in the transaction, if foreign currency is used. Null otherwise |
foreignCurrencyAmount | Double | Optional | The amount used in foreign currency |
exchangeRate | Double | optional | The exchange rate used, if a foreign currency is used. Null otherwise |
responseCode | Integer | Optional | If the request failed then PAGA will send the exception code else the value of the exception code will be 0(zero). |
errorMessage | String | Optional | Describes the status of the request. Whether it succeeds or fails |
Sample Response
{
"message":"Thank for registering to paga. We will send SMS to +251911010862 with a registeration code. Please use www.mypaga.com or dial 636 to set up your user PIN.",
"errorMessage": null, "responseCode":0 ,
"referenceNumber":0, "merchantReferenceNumber":0,
"dateTimeUTC":0, "transactionType":0,
"amount":0, "transactionId":0,
"channel":0, "byAgent":0, "currency":0,
"foreignCurrencyAmount":0, "exchangeRate":0,
}
Get Transaction Details by Invoice Number
This service allows the merchant to verify the status and details of an executed process or to determine if a transaction was indeed executed on the system using the pre-shared transaction invoice number. The invoice number used is unique across the platform, so merchant aggregators checking for transactions status across multiple users should use this method.
Request Parameters
Argument Name | Type | Requirement | Description |
|---|---|---|---|
invoiceNumber | String | Required | The invoice number returned as part of a previously executed transaction |
Sample request
URL:
https://www.mypaga.com/paga-webservices/merchant-rest/secured/getTransactionDetailsByInvoiceNumber
Http Headers:
principal: publicId (merchant business publicId)
credentials: p@ssword1
hash: hashed with SHA-512 algorithm of the appended params containing(invoiceNumber + apikey)
Content-Type: application/json
Request Body:
{"invoiceNumber":"242355"}
Response Parameters
Argument Name | Type | Requirement | Description |
|---|---|---|---|
referenceNumber | String | Required | The unique reference number code provided with the request |
status | String | optional | The status of the transaction, if the transaction was found on the system. Note that any status other than UKNOWN means that the transaction was found on the system |
merchantReference | String | optional | The executing customer's reference number on the merchant's system as provided by the customer during transaction processing (eg. customer account number, invoice number etc.) |
dateTimeUTC | dateTime | optional | The transaction date and time provided in UTC standard time |
transactionType | String | optional | An enum representing the type of transaction executed |
amount | Double | optional | The case amount of the transaction. Note that this may be different from the amount remitted to the biller or actually charged to the customer depending on any fees included in the transaction. |
transactionId | String | optional | The common transaction id shared with all parties involved in the transaction |
channel | String | optional | The channel on which the transaction was executed |
byAgent | Boolean | optional | Whether the transaction was executed at an agent (true) or not (false) |
currency | String | optional | The currency used in the transaction, if foreign currency is used. Null otherwise |
foreignCurrencyAmount | Double | Optional | The amount used in foreign currency |
exchangeRate | Double | optional | The exchange rate used, if a foreign currency is used. Null otherwise |
responseCode | Integer | Optional | If the request failed then PAGA will send the exception code else the value of the exception code will be 0(zero). |
errorMessage | String | Optional | Describes the status of the request. Whether it succeeds or fails |
Sample response
{
"message":"Thank for registering to paga. We will send SMS to +251911010862 with a registeration code. Please use www.mypaga.com or dial 636 to set up your user PIN.","errorMessage":
null,"responseCode":0, "referenceNumber":0,"merchantReferenceNumber":0,
"dateTimeUTC":0, "transactionType":0, "amount":0,
"transactionId":0, "channel":0, "byAgent":0,
"currency":0, "foreignCurrencyAmount":0, "exchangeRate":0
}
On this page: