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

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

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,
}

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

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

Response Parameters

Argument Name	Type	Requirement	Description

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

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

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

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

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

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

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

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

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