Merchant Service API

📘
NOTE
Please note that the hash parameter must contain the values of those params mentioned in the same order and the Hash key (the key given by Paga) hashed with SHS-512 algorithm ! (excluding the + sign)
Test base-url : https://beta.mypaga.com/
Live base-url: https://www.mypaga.com/

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.

Service Method: getTransactionDetails

Request URL
https://www.mypaga.com/paga-webservices/merchant-rest/secured/getTransactionDetails

Request Parameters

Argument Name	Type	Requirement	Description
referenceNumber	String	required	The unique transaction code returned as part of a previously executed transaction

POST URL: https://www.mypaga.com/paga-webservices/merchant-rest/secured/getTransactionDetails HTTP/1.1
 
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"
}

{  
   "amount":1500,
   "dateTimeUTC":1564566479963,
   "errorMessage":null,
   "channel":"ONLINE",
   "foreignCurrency":null,
   "foreignCurrencyAmount":0,
   "transactionId":"SB6N9",
   "responseCode":0,
   "byAgent":false,
   "transactionType":"CUSTOMER_BILL_PAY",
   "referenceNumber":"242355",
   "exchangeRate":null,
   "currency":"NGN",
   "merchantReference":"441f4e10-712d-42d6-a5e3-cd97586ae389",
   "status":"SUCCESSFUL"
}

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	Amount used during 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
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

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.

ServiceMethod: getTransactionDetailsByInvoiceNumber

Request URL
https://www.mypaga.com/paga-webservices/merchant-rest/secured/getTransactionDetailsByInvoiceNumber

Request Parameters

Argument Name	Type	Requirement	Description
invoiceNumber	String	Required	The invoice number returned as part of a previously executed transaction

POST URL:https://www.mypaga.com/paga-webservices/merchant-rest/secured/getTransactionDetailsByInvoiceNumber HTTP/1.1
 
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"
}

{  
   "amount":5000,
   "dateTimeUTC":1564576845597,
   "errorMessage":null,
   "channel":"ONLINE",
   "foreignCurrencyAmount":0,
   "transactionId":"TZHYT",
   "responseCode":0,
   "byAgent":false,
   "transactionType":"CUSTOMER_BILL_PAY",
   "referenceNumber":"1517775",
   "exchangeRate":0,
   "invoiceNumber":"242355",
   "currency":"NGN",
   "merchantReference":"a1ffcb7d-db75-4d8b-ac5c-739b64a95936",
   "status":"SUCCESSFUL"
}

Response parameters

Argument Name	Type	Requirement	Description
referenceNumber	String	Required	The unique reference number code provided with the request
amount	Double	Optional	Amount used during 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.
dateTimeUTC	DateTime	Optional	The transaction date and time provided in UTC standard time
errorMessage	String	Optional	Describes the status of the request. Whether it succeeds or fails
channel	String	Optional	The channel on which the transaction was executed
foreignCurrencyAmount	Double	Optional	The amount used in foreign currency
transactionId	String	Optional	The common transaction id shared with all parties involved in the transaction
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).
byAgent	Boolean	Optional	Whether the transaction was executed at an agent (true) or not (false)
transactionType	String	Optional	An enum representing the type of transaction executed
invoiceNumber	String	Required	The invoice number returned as part of a previously executed transaction
currency	String	Optional	The currency used in the transaction, if foreign currency is used. Null otherwise
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.)
status	String		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

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 on 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.

Service Method: getProcessDetails

Request URL
https://www.mypaga.com/paga-webservices/merchant-rest/secured/getProcessDetails

Request parameters

Argument Name	Type	Requirement	Description
processCode	String	Required	The process code returned as part of a previously executed transaction.

POST URL: https://www.mypaga.com/paga-webservices/merchant-rest/secured/getProcessDetails HTTP/1.1
 
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"
}

{  
   "amount":100,
   "dateTimeUTC":1558316919037,
   "processCode":"1822231066919037",
   "errorMessage":null,
   "processType":"MERCHANT_PAYMENT",
   "customerAccount":"111-2140",
   "responseCode":0,
   "status":"SUCCESSFUL"
}

Response Parameters

Argument Name	Type	Requirement	Description
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.
dateTimeUTC	DateTime	Optional	The transaction date and time provided in UTC standard time
processCode	String	Required	The process code provided with the request
errorMessage	String	Optional	Describes the status of the request. Whether it succeeds or fails
processType	String	Optional	An enum representing the type of payment process executed
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.)
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).
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

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.

Service Method: reconciliationReport

Request URL
https://www.mypaga.com/paga-webservices/merchant-rest/secured/reconciliationReport

Request Parameters

Argument Name	Type	Requirement	Description
periodStartDateTimeUTC	DateTime	Required	The datetime period for the reconciliation report to start
periodEndDateTimeUTC	DateTime	Required	The datetime period for the reconciliation report ends

POST URL: https://www.mypaga.com/paga-webservices/merchant-rest/secured/reconciliationReport HTTP/1.1 
Http Headers:
    principal: publicId (merchant business publicId)
    credentials: p@ssword1
    hash: hashed with SHA-512 algorithm of the appended params          containing(periodEndDateTimeUTC + periodStartDateTimeUTC  + apikey)
    Content-Type: application/json
 
Request Body: 
{  
   "periodStartDateTimeUTC":"242355",
   "periodEndDateTimeUTC":"242355"
}

{  
   "errorMessage":null,
   "responseCode":0,
   "reconciliationItems":[  
      {  
         "pagaProcessCode":0,
         "description":null,
         "transactionDatetimeUTC":0,
         "referenceNumber":"123442",
         "amount":0,
         "status":"SUCCESSFUL"
      }
   ]
}

Response Parameters

Argument Name	Type	Requirement	Description
reconciliationItems	ReconciliationItem	Required	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	Optional	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
description	String	Optional	Description for the process
transactionDatetimeUTC	DateTime	Optional	The transaction date and time provide in UTC standard time
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.)
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.

5. Get Foreign Exchange Rate

This service provides the mechanism to determine the exchange rate.

Service Method : getForeignExchangeRate

Request URL
https://www.mypaga.com/paga-webservices/merchant-rest/secured/getForeignExchangeRate

Request Parameters

Argument Name	Type	Requirement	Description
baseCurrency	CurrencyCode (restricted string)	Required
foreignCurrency	CurrencyCode (restricted string)	Required

POST URL: https://www.mypaga.com/paga-webservices/merchant-rest/secured/getForeignExchangeRate HTTP/1.1
 
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"
}

{  
   "sellRate":360.00044,
   "errorMessage":null,
   "foreignCurrency":"USD",
   "baseCurrency":"NGN",
   "responseCode":0,
   "buyRate":360.00044
}

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

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.

Service Method: refundBillPay

Request URL
https://www.mypaga.com/paga-webservices/merchant-rest/secured/refundBillPay

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	Required	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
customerPhoneNumber	String	Required	The phone number of the customer that performed the operation

POST URL:https://www.mypaga.com/paga-webservices/merchant-rest/secured/refundBillPay HTTP/1.1
 
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":true, 
        "fullRefund":true, "refundAmount":"242355", 
        "currency":"NGN", "reason":"242355",
        "customerPhoneNumber":"08011111111"
    }

{  
   "exchangeRate":0,
   "refundTransactionId":"K03PD",
   "originalReferenceNumber":"BP-C_20190802114654120_1517873_F400G",
   "errorMessage":null,
   "currency":null,
   "responseCode":0,
   "refundAmount":3000
}

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
refundAmount	Double	Required	Amount refunded if the refund is partial
originalReferenceNumber	String	Required	Reference number of the original transaction as provided with the request
currency 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
errorMessage	String	Optional	Describes the status of the request. Whether it succeeds or fails
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).

7. Get Transaction Details By Merchant Reference Number

This service allows the merchant to verify the status and details of an executed transaction or to determine if a transaction was indeed executed on the system using the merchant reference number. Merchant aggregators checking for transaction status across multiple users should use this method.

Service Method: getTransactionDetailsByMerchantReference

Request URL
https://www.mypaga.com/paga-webservices/merchant-rest/secured/getTransactionDetailsByMerchantReference

Request Parameter

Argument Name	Type	Requirement	Description
merchantReference	String	Mandatory	The Merchant unique transaction code used as part of a previously executed transaction

Sample Code

POST URL:https://www.mypaga.com/paga-webservices/merchant-rest/secured/getTransactionDetailsByMerchantReference
 
Http Headers:
    principal:      publicId (merchant business publicId)
    credentials:    p@ssword1
    hash:           hashed with SHA-512 algorithm of the appended params  
    		    containing(merchantReference+ apikey)
    Content-Type:   application/json
 
Request Body: 
{
   "merchantReference":"conn-51452672"
}

{
    "responseCode": 0,
    "errorMessage": null,
    "invoiceNumber": null,
    "referenceNumber": "SCN-C_202004160844079_1524135_JG218",
    "status": "SUCCESSFUL",
    "merchantReference": "conn-51452672",
    "dateTimeUTC": 1587023047010,
    "transactionType": "CUSTOMER_SEND_CASH_TO_CUSTOMER",
    "amount": 8000.0,
    "transactionId": "JG218",
    "channel": "BUSINESS_API",
    "byAgent": false,
    "currency": "NGN",
    "exchangeRate": null,
    "foreignCurrencyAmount": null
}

Response Parameters

Argument Name	Type	Requirement	Description
responseCode	Integer	Mandatory	If the request failed then PAGA will send the exception code else the value of the exception code will be 0(zero)
errorMessage	String	Mandatory	Describes the status of the request. Whether it succeeds or fails
referenceNumber	String	Mandatory	The unique reference number code provided with the request
status	String	Mandatory	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	Mandatory	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	Mandatory	An enum representing the type of transaction executed
amount	Double	Mandatory	Amount used during 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	Mandatory	The common transaction id shared with all parties involved in the transaction
channel	String	Mandatory	The channel on which the transaction was executed
byAgent	Boolean	Mandatory	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
exchangeRate	Double	Optional	The exchange rate used, if a foreign currency is used. Null otherwise
foreignCurrencyAmount	Double	Optional	The amount used in foreign currency

📘NOTE

1. Get Transaction Details

2. Get Transaction Details by Invoice Number

3. Get Process Details

4. Reconciliation Report

5. Get Foreign Exchange Rate

6. Refund Bill Pay

7. Get Transaction Details By Merchant Reference Number

📘
NOTE