Merchant Services Operations
Overview
The following sections provide a more detailed documentation on the Merchant service operations.
1. 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,
}
2. 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
}
3. Get Process Details
This service allows the merchant to verify the status and details of an executed process or to determine if a process was indeed executed ion the system using the pre-shared process code. The process code used is unique by merchant so merchant aggregators checking for transactions stratus across multiple users should use the getTransactionDetails method.
Request Parameters
Argument Name | Type | Requirement | Description |
|---|---|---|---|
processCode | String | Required | The process code returned as part of a previously executed transaction |
Sample Request
URL:
https://www.mypaga.com/paga-webservices/merchant-rest/secured/getProcessDetails
Http Headers:
principal: publicId (merchant business publicId)
credentials: p@ssword1
hash: hashed with SHA-512 algorithm of the appended params containing(processCode+ apikey)
Content-Type: application/json
Request Body:
{"processCode":"242355"}
Response parameters
Argument Name | Type | Requirement | Description |
|---|---|---|---|
processCode | String | Require | The process code provided with the request |
status | String | optional | The status of the process, if the transaction was found on the system. Note that any status other than UKNOWN means that the process was found on the system |
customerAccount | 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 |
processType | String | optional | An enum representing the type of payment process executed |
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 |
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. |
Response sample
{
"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 , "processCode":0,
"customerAccount":0, "dateTimeUTC":0, "processType":0,
"amount":0, "status":0
}
4. Reconciliation Report
This service provides the mechanism for Paga to retrieve reconciled reports on the date range provided containing list of processes and transactions.
Request Parameters
Argument Name | Type | Requirement | Description |
|---|---|---|---|
periodStartDateTimeUTC | Date | Required | The datetime period for the reconciliation report to start |
periodEndDateTimeUTC | Date | Required | The datetime period for the reconciliation report ends |
Sample Request
URL:
https://www.mypaga.com/paga-webservices/merchant-rest/secured/reconciliationReport
Http Headers:
principal: publicId (merchant business publicId)
credentials: p@ssword1
hash: hashed with SHA-512 algorithm of the appended params containing(periodStartDateTimeUTC + periodEndDateTimeUTC + apikey)
Content-Type: application/json
Request Body:
{"periodStartDateTimeUTC":"242355", "periodEndDateTimeUTC":"242355"}
Response Parameters
Argument Name | Type | Requirement | Description |
|---|---|---|---|
reconciliationItems | ReconciliationItem | Require | A list of reconciliation items |
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 |
ReconciliationItem:
Argument Name | Type | Requirement | Description |
|---|---|---|---|
pagaProcessCode | String | Require | The process code provided with the request |
status | String | optional | The status of the process, if the transaction was found on the system. Note that any status other than UKNOWN means that the process was found on the system |
referenceNumber | 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.) |
transactionDatetimeUTC | dateTime | optional | The transaction date and time provide in UTC standard time |
description | String | optional | Description for the process |
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. |
Response Sample
{
"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 , reconciliationItems:
[{
"pagaProcessCode":0, "description":0,
"transactionDatetimeUTC":0, "referenceNumber":0,
"amount":0,"status":0
}]
}
5. Get Foreign Exchange Rate
This service provides the mechanism for Paga to submit a payment notification to the merchant systems. Execution of this service should trigger payment notification logic in merchant system.
Request Parameters
Argument Name | Type | Requirement | Description |
|---|---|---|---|
baseCurrency | CurrencyCode (restricted string) | Required |
|
foreignCurrency | CurrencyCode (restricted string) | Required |
|
Sample Request
URL:
https://www.mypaga.com/paga-webservices/merchant-rest/secured/getForeignExchangeRate
Http Headers:
principal: publicId (merchant business publicId)
credentials: p@ssword1
hash: hashed with SHA-512 algorithm of the appended params containing(baseCurrency + foreignCurrency + apikey)
Content-Type: application/json
Request Body:
{"baseCurrency":"242355", "foreignCurrency":"242355"}
Response Parameters
Argument Name | Type | Requirement | Description |
|---|---|---|---|
baseCurrency | CurrencyCode (restricted string) | Required |
|
foreignCurrency | CurrencyCode (restricted string) | Required |
|
buyRate | double | Required | The exchange rate at which Paga will buy the foreign currency in exchange for base currency |
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 |
sellRate | double | Required | The rate at which Paga will sell the foreign currency in exchange for the base currency |
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 , "reconciliationItems":
[{
"pagaProcessCode":0, "description":0,
"transactionDatetimeUTC":0, "referenceNumber":0,
"amount":0,"status":0
}]
}
6. Refund Bill Pay
This service allows merchants to fully or partially refund bill payment previously made to them by a customer. The refund specified may be in full or a partial amount. Full refunds may include or exclude customer fee.
Request Parameters
Argument Name | Type | Requirement | Description |
|---|---|---|---|
referenceNumber | String | Required | The unique reference number provided as part of the original transaction which identifies the transaction to be refunded. |
includesCustomerFee | Boolean | Optional | Indicates whether the refund includes the customer fee (true) or not (false) |
fullRefund | Boolean | Required | Indicates whether the refund is full or partial |
refundAmount | Double | Optional | Only provided for a partial refund, this indicates the amount to be refunded. |
currency | CurrencyCode | Optional | The currency used in the transaction. |
reason | String | Optional | Human readable reason for refund |
Sample Request
URL:
https://www.mypaga.com/paga-webservices/merchant-rest/secured/refundBillPay
Http Headers:
principal: publicId (merchant business publicId)
credentials: p@ssword1
hash: hashed with SHA-512 algorithm of the appended params containing(referenceNumber + refundAmount + customerPhoneNumber + apikey)
Content-Type: application/json
Request Body:
{
"referenceNumber":"242355", "includesCustomerFee":"242355",
"fullRefund":"242355", "refundAmount":"242355",
"currency":"242355", "reason":"242355"
}
Response Parameters
Argument Name | Type | Requirement | Description |
|---|---|---|---|
refundTransactionId | String | Required | A short/common transaction id of the refund which is shared with all parties. Note that this may not be unique over a long period of time |
refundReferenceNumber | String | Required | A unique reference number that uniquely identifies the refund transaction |
refundAmount | Double | Required | Amount refunded if the refund is partial |
refundedCustomerFee | Double | Optional | Fee amount refunded if the refund includes fee |
originalReferenceNumber | String | Required | Reference number of the original transaction as provided with the request |
currency | CurrencyCode | Optional | The currency used in the refund transaction if a foreign currency is used |
exchangeRate | Double | Optional | The exchange rate used if a foreign currency was used |
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 ,
"refundTransactionId":0, "refundReferenceNumber":0,
"refundedCustomerFee":0, "originalReferenceNumber":0,
"refundAmount":0,"currency":0, "exchangeRate": 0.00
}
On this page: