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.
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
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
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
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"}