Payment Query

This guideline explains how to apply the corresponding source code in a merchant's website application to form the mandatory payment request parameters for UPP payment query processing and send them to PayMaster.

Java

Step 1 : Library

The merchant must include the PayMaster Merchant Plug-In (MPI) Java library, PayMaster.jar, in their application.

Step 2 : Import

For UPP payments, the merchant should import the following into their code:

• com.PayMaster.Entities.PayMasterEntity
• com.PayMaster.PropertiesReader.PropertiesReader
• com.PayMaster.MessageRequestBuilder.WebservicePaymentRequestMessageBuilder

Step 3 : Source Code

import com.PayMaster.Entities.PayMasterEntity;
import com.PayMaster.PropertiesReader.PropertiesReader;
import com.PayMaster.MessageRequestBuilder.WebservicePaymentRequestMessageBuilder;

// Declare variable for Payment Master Properties - 1st Parameter = File Path, 2nd Parameter = File Name
PropertiesReader propertiesReader = new PropertiesReader("./PayMasterProperties/", "UPPPayment.properties");

// Declare variable for Payment Master Entity
PayMasterEntity paymentRequestEntity = new PayMasterEntity();

// Get all the parameter values from the user side and set them into Payment Master Entity
paymentRequestEntity.setter("PaymentID", "U02"); 
paymentRequestEntity.setter("MerchantID", "000010000099939"); 
paymentRequestEntity.setter("ServiceID", "FNX"); 
paymentRequestEntity.setter("MerchRefNo", "MYB2023030315435025LL"); 
paymentRequestEntity.setter("QueryRespURL", "https://XXX.XXXXX.XXX/query.jsp");

// Call Payment Master Payment Request Message Builder to generate the message
WebservicePaymentRequestMessageBuilder messageBuilder = new WebservicePaymentRequestMessageBuilder();
messageBuilder.buildUPPQueryRequestMessage(paymentRequestEntity, propertiesReader);

// Retrieve values from Payment Master Entity
String MerchantID = paymentRequestEntity.getter("MerchantID");
String CardNo = paymentRequestEntity.getter("CardNo");
String TxnDtTm = paymentRequestEntity.getter("TxnDtTm");
String TxnAmt = paymentRequestEntity.getter("TxnAmt");
String TxnStatus = paymentRequestEntity.getter("TxnStatus");
String CurrCode = paymentRequestEntity.getter("CurrCode");
String AuthIDRespCode = paymentRequestEntity.getter("AuthIDRespCode");
String ExpTxnAmt = paymentRequestEntity.getter("ExpTxnAmt");
String RetrievalRefNo = paymentRequestEntity.getter("RetrievalRefNo");
String OrgRespCode = paymentRequestEntity.getter("OrgRespCode");
String OrigTxnAmt = paymentRequestEntity.getter("OrigTxnAmt");
String OrigCurrCode = paymentRequestEntity.getter("OrigCurrCode");
String TxnChannel = paymentRequestEntity.getter("TxnChannel");
String FICode = paymentRequestEntity.getter("FICode");
String PymtGwRefNo = paymentRequestEntity.getter("PymtGwRefNo");
String TxnStatDetCde = paymentRequestEntity.getter("TxnStatDetCde");
String TxnStatMsg = paymentRequestEntity.getter("TxnStatMsg");
String ServiceID = paymentRequestEntity.getter("ServiceID");
String MerchHostID = paymentRequestEntity.getter("MerchHostID");
String MerchSessionID = paymentRequestEntity.getter("MerchSessionID");
String MerchRefNo = paymentRequestEntity.getter("MerchRefNo");
String OrderRefNo = paymentRequestEntity.getter("OrderRefNo");
String QueryStatus = paymentRequestEntity.getter("QueryStatus");
String FPXRefNo = paymentRequestEntity.getter("FPXRefNo");
String UppPymtMode = paymentRequestEntity.getter("UppPymtMode");
String OrigRespCode = paymentRequestEntity.getter("OrigRespCode");
String ExporigTxnAmt = paymentRequestEntity.getter("ExporigTxnAmt");

.....

Step 4 : Indicate PayMaster Properties File Location

The merchant must specify the location of the PayMaster Properties File using PropertiesReader.

Step 5: Assign Values to PayMaster Request Entity

The merchant should assign values to the PayMaster Request Entity. The code must include all fields as specified in the sample code, as they are mandatory.

• The setter function is used to assign values, accepting two parameters: setter(parameter name, parameter value).

Step 6 : Call the Web Service Payment Request Message Builder

Once all mandatory values are assigned, the merchant should call the Web Service Payment Request Message Builder with the buildUPPPaymentQueryRequest function.

• The Payment Query Request message will be generated and submitted to the PayMaster Gateway.
• The query response received from the PayMaster Gateway will be processed and assigned back to the PayMaster Request Entity.

Step 7 : Retrieve Values from PayMaster Request Entity

The merchant can use the same PayMaster Request Entity to retrieve information from the query response.

• The getter function is used to retrieve values, accepting one parameter: getter(parameter name).

Refer to UPP Payment Query Parameters for the fields supported by the PayMaster Merchant Plug-In (MPI).

.Net

Step 1 : Library

The merchant must include the PayMaster Merchant Plug-In (MPI) .NET library, PayMaster.dll, in their application.

Step 2 : Namespace

For UPP payments, the merchant shall include the following namespaces in the merchant code:

• using com.PayMaster.Entities
• using com.PayMaster.Properties
• using com.PayMaster.MessageRequestBuilder

Step 3 : Source Code

using com.PayMaster.Entities;
using com.PayMaster.Properties;
using com.PayMaster.MessageRequestBuilder;

// Declare variable for Payment Master Properties - 1st Parameter = File Path, 2nd Parameter = File Name
PropertiesReader propertiesReader = new PropertiesReader("./PayMasterProperties/", "UPPPayment.properties");

// Declare variable for Payment Master Entity
PayMasterEntity uppPaymentRequestEntity = new PayMasterEntity();

// Get all the parameter values from the user side and set them into Payment Master Entity
uppPaymentRequestEntity.setter("PaymentID", "U02"); 
uppPaymentRequestEntity.setter("MerchantID", "000010000099939"); 
uppPaymentRequestEntity.setter("ServiceID", "FNX"); 
uppPaymentRequestEntity.setter("MerchRefNo", "MYB2023030315435025LL"); 
uppPaymentRequestEntity.setter("QueryRespURL", "https://XXX.XXXXX.XXX/query.jsp");

// Call Payment Master Web Service Payment Request Message Builder for UPP query request
WebServicePaymentRequestMessageBuilder uppMessageBuilder = new WebServicePaymentRequestMessageBuilder();
await uppMessageBuilder.buildUPPPaymentQueryRequest(uppPaymentRequestEntity, propertiesReader);

// Retrieve values from Payment Master Entity
string MerchantID = uppPaymentRequestEntity.getter("MerchantID");
string CardNo = uppPaymentRequestEntity.getter("CardNo");
string TxnDtTm = uppPaymentRequestEntity.getter("TxnDtTm");
string TxnAmt = uppPaymentRequestEntity.getter("TxnAmt");
string TxnStatus = uppPaymentRequestEntity.getter("TxnStatus");
string CurrCode = uppPaymentRequestEntity.getter("CurrCode");
string AuthIDRespCode = uppPaymentRequestEntity.getter("AuthIDRespCode");
string ExpTxnAmt = uppPaymentRequestEntity.getter("ExpTxnAmt");
string RetrievalRefNo = uppPaymentRequestEntity.getter("RetrievalRefNo");
string OrgRespCode = uppPaymentRequestEntity.getter("OrgRespCode");
string OrigTxnAmt = uppPaymentRequestEntity.getter("OrigTxnAmt");
string OrigCurrCode = uppPaymentRequestEntity.getter("OrigCurrCode");
string TxnChannel = uppPaymentRequestEntity.getter("TxnChannel");
string FICode = uppPaymentRequestEntity.getter("FICode");
string PymtGwRefNo = uppPaymentRequestEntity.getter("PymtGwRefNo");
string TxnStatDetCde = uppPaymentRequestEntity.getter("TxnStatDetCde");
string TxnStatMsg = uppPaymentRequestEntity.getter("TxnStatMsg");
string ServiceID = uppPaymentRequestEntity.getter("ServiceID");
string MerchHostID = uppPaymentRequestEntity.getter("MerchHostID");
string MerchSessionID = uppPaymentRequestEntity.getter("MerchSessionID");
string MerchRefNo = uppPaymentRequestEntity.getter("MerchRefNo");
string OrderRefNo = uppPaymentRequestEntity.getter("OrderRefNo");
string QueryStatus = uppPaymentRequestEntity.getter("QueryStatus");
string FPXRefNo = uppPaymentRequestEntity.getter("FPXRefNo");
string UppPymtMode = uppPaymentRequestEntity.getter("UppPymtMode");
string OrigRespCode = uppPaymentRequestEntity.getter("OrigRespCode");
string ExporigTxnAmt = uppPaymentRequestEntity.getter("ExporigTxnAmt");
.....

Step 4 : Indicate PayMaster Properties File Location

The merchant must specify the location of the PayMaster Properties File using PropertiesReader.

Step 5 : Assign Values to Payment Request Entity

The merchant should assign values to the PayMaster Request Entity. The code must include all the fields as stated in the sample code, as they are mandatory.

• The setter function is used to assign values, accepting two parameters: setter(parameter name, parameter value).

Step 6 : Call the Web Service Payment Request

Once all mandatory values are assigned, the merchant should call the Web Service Payment Request Message Builder with the buildUPPPaymentQueryRequest function.

• The Payment Query Request message will be generated and submitted to the PayMaster Gateway.
• The query response received from the PayMaster Gateway will be processed and assigned back to the PayMaster Request Entity.

Step 7 : Retrieve Values from PayMaster Request Entity

The merchant can use the same PayMaster Request Entity to retrieve information from the query response.

• The getter function is used to retrieve values, accepting one parameter: getter(parameter name).

Refer to UPP Payment Query Parameters for the fields supported by the PayMaster Merchant Plug-In (MPI).

PHP

Step 1 : Library

The merchant must include the PayMaster Merchant Plug-In (MPI) PHP library, PayMaster.phar, in their application.

Step 2 : Merchant Code

For UPP payment queries, the merchant should import the following components into their code:

• PropertiesReader - to read the properties files.
• PayMasterEntity – to assign all the acceptable values for PayMaster UPP payment query.
• WebServicePaymentRequestMessageBuilder – to generate the PayMaster UPP payment query request message.

Step 3 : Source Code

<?php
use com\PayMaster\Entities\PayMasterEntity;
use com\PayMaster\PropertiesReader\PropertiesReader;
use com\PayMaster\MessageRequestBuilder\WebServicePaymentRequestMessageBuilder;
use com\PayMaster\Import\ImportFile;

// Locate the absolute path of PayMaster.phar
$basePath = 'phar://<PayMaster.phar path>/';
include_once $basePath . 'com/PayMaster/Import/ImportFile.php';
$import = new ImportFile();
$import->includeFile($basePath);

// Declare variable for Payment Master Properties - 1st Parameter = File Path, 2nd Parameter = File Name
$propertiesReader = new PropertiesReader();
$propertiesReader->PropertiesReader("./PayMasterProperties/", "UPPPayment.ini");

// Declare variable for Payment Master Entity
$paymentRequestEntity = new PayMasterEntity();

// Set Values to Payment Master Entity
$paymentRequestEntity->setter("PaymentID", "U02"); 
$paymentRequestEntity->setter("MerchantID", "000010000099939"); 
$paymentRequestEntity->setter("ServiceID", "FNX"); 
$paymentRequestEntity->setter("MerchRefNo", "MYB2023030315435025LL"); 
$paymentRequestEntity->setter("QueryRespURL", "https://XXX.XXXXX.XXX/query.jsp");

// Call Payment Master Payment Response Message Builder to set value
$webServicePaymentRequestMessageBuilder = new WebServicePaymentRequestMessageBuilder();
$webServicePaymentRequestMessageBuilder->buildUPPQueryRequestMessage($paymentRequestEntity, $propertiesReader);

// Retrieve values from Payment Master Entity
$MerchantID = $paymentRequestEntity->getter("MerchantID");
$CardNo = $paymentRequestEntity->getter("CardNo");
$TxnDtTm = $paymentRequestEntity->getter("TxnDtTm");
$TxnAmt = $paymentRequestEntity->getter("TxnAmt");
$TxnStatus = $paymentRequestEntity->getter("TxnStatus");
$CurrCode = $paymentRequestEntity->getter("CurrCode");
$AuthIDRespCode = $paymentRequestEntity->getter("AuthIDRespCode");
$ExpTxnAmt = $paymentRequestEntity->getter("ExpTxnAmt");
$RetrievalRefNo = $paymentRequestEntity->getter("RetrievalRefNo");
$OrgRespCode = $paymentRequestEntity->getter("OrgRespCode");
$OrigTxnAmt = $paymentRequestEntity->getter("OrigTxnAmt");
$OrigCurrCode = $paymentRequestEntity->getter("OrigCurrCode");
$TxnChannel = $paymentRequestEntity->getter("TxnChannel");
$FICode = $paymentRequestEntity->getter("FICode");
$PymtGwRefNo = $paymentRequestEntity->getter("PymtGwRefNo");
$TxnStatDetCde = $paymentRequestEntity->getter("TxnStatDetCde");
$TxnStatMsg = $paymentRequestEntity->getter("TxnStatMsg");
$ServiceID = $paymentRequestEntity->getter("ServiceID");
$MerchHostID = $paymentRequestEntity->getter("MerchHostID");
$MerchSessionID = $paymentRequestEntity->getter("MerchSessionID");
$MerchRefNo = $paymentRequestEntity->getter("MerchRefNo");
$OrderRefNo = $paymentRequestEntity->getter("OrderRefNo");
$QueryStatus = $paymentRequestEntity->getter("QueryStatus");
$FPXRefNo = $paymentRequestEntity->getter("FPXRefNo");
$UppPymtMode = $paymentRequestEntity->getter("UppPymtMode");
$OrigRespCode = $paymentRequestEntity->getter("OrigRespCode");
$ExporigTxnAmt = $paymentRequestEntity->getter("ExporigTxnAmt");

Step 4 : Locate Absolute Path of PayMaster.phar

The merchant must specify the absolute path of PayMaster.phar as the basePath in the merchant source code (line 7 in the example above).

Example:$basePath=’phar://<absolute path of PayMaster.phar>/’

Step 5 : Assign Values to PayMaster Request Entity

The merchant should assign values to the PayMaster Request Entity. The code must include all fields as specified in the sample code, as they are mandatory.

• The setter function is used to assign values, accepting two parameters: setter(parameter name, parameter value).

Step 6 : Call the Web Service Payment Request

Once all mandatory values are assigned, the merchant should call the Web Service Payment Request Message Builder with the buildUPPQueryRequestMessage function.

• The Payment Query Request message will be generated and submitted to PayMaster Gateway.
• The query response received from the PayMaster Gateway will be processed and assigned back to the PayMaster Request Entity.

Step 7 : Retrieve Values from PayMaster Request Entity

The merchant can use the same PayMaster Request Entity to retrieve information from the query response.

• The getter function is used to retrieve values, accepting one parameter: getter(parameter name).

Refer to UPP Payment Query Parameters for the fields supported by the PayMaster Merchant Plug-In (MPI).

Python

Step 1 : Packages

The merchant must set up and include the PayMaster Merchant Plug-In (MPI) Python packages in their application.

Step 2 : Import

For UPP payments, the merchant should include the following in their code:

• PropertiesReader – to read the properties files.
• PayMasterEntity – to assign all the acceptable values for PayMaster UPP payment query.
• WebServicePaymentRequestMessageBuilder – to generate the PayMaster UPP payment query request message.

Step 3 : Source Code

from com.PayMaster.Entities.PayMasterEntity import PayMasterEntity
from com.PayMaster.PropertiesReader.PropertiesReader import PropertiesReader
from com.PayMaster.MessageRequestBuilder.WebServicePaymentRequestMessageBuilder import WebServicePaymentRequestMessageBuilder

# Declare variable for Payment Master Properties - 1st Parameter = File Path, 2nd Parameter = File Name
propertiesReader = PropertiesReader("./PayMasterProperties/", "UPPPayment.properties")

# Declare variable for Payment Master Entity
uppPaymentRequestEntity = PayMasterEntity()

# Set Values to Payment Master Entity
uppPaymentRequestEntity.setter("PaymentID", "U02")
uppPaymentRequestEntity.setter("MerchantID", "000010000099939")
uppPaymentRequestEntity.setter("ServiceID", "FNX")
uppPaymentRequestEntity.setter("MerchRefNo", "MYB2023030315435025LL")
uppPaymentRequestEntity.setter("QueryRespURL", "https://XXX.XXXXX.XXX/query.jsp")

# Call Payment Master Web Service Payment Request Message Builder for UPP query request
uppMessageBuilder = WebServicePaymentRequestMessageBuilder()
uppMessageBuilder.buildUPPPaymentQueryRequest(uppPaymentRequestEntity, propertiesReader)

# Retrieve values from Payment Master Entity
MerchantID = uppPaymentRequestEntity.getter("MerchantID")
CardNo = uppPaymentRequestEntity.getter("CardNo")
TxnDtTm = uppPaymentRequestEntity.getter("TxnDtTm")
TxnAmt = uppPaymentRequestEntity.getter("TxnAmt")
TxnStatus = uppPaymentRequestEntity.getter("TxnStatus")
CurrCode = uppPaymentRequestEntity.getter("CurrCode")
AuthIDRespCode = uppPaymentRequestEntity.getter("AuthIDRespCode")
ExpTxnAmt = uppPaymentRequestEntity.getter("ExpTxnAmt")
RetrievalRefNo = uppPaymentRequestEntity.getter("RetrievalRefNo")
OrgRespCode = uppPaymentRequestEntity.getter("OrgRespCode")
OrigTxnAmt = uppPaymentRequestEntity.getter("OrigTxnAmt")
OrigCurrCode = uppPaymentRequestEntity.getter("OrigCurrCode")
TxnChannel = uppPaymentRequestEntity.getter("TxnChannel")
FICode = uppPaymentRequestEntity.getter("FICode")
PymtGwRefNo = uppPaymentRequestEntity.getter("PymtGwRefNo")
TxnStatDetCde = uppPaymentRequestEntity.getter("TxnStatDetCde")
TxnStatMsg = uppPaymentRequestEntity.getter("TxnStatMsg")
ServiceID = uppPaymentRequestEntity.getter("ServiceID")
MerchHostID = uppPaymentRequestEntity.getter("MerchHostID")
MerchSessionID = uppPaymentRequestEntity.getter("MerchSessionID")
MerchRefNo = uppPaymentRequestEntity.getter("MerchRefNo")
OrderRefNo = uppPaymentRequestEntity.getter("OrderRefNo")
QueryStatus = uppPaymentRequestEntity.getter("QueryStatus")
FPXRefNo = uppPaymentRequestEntity.getter("FPXRefNo")
UppPymtMode = uppPaymentRequestEntity.getter("UppPymtMode")
OrigRespCode = uppPaymentRequestEntity.getter("OrigRespCode")
ExporigTxnAmt = uppPaymentRequestEntity.getter("ExporigTxnAmt")

Step 4 : Indicate PayMaster Properties File Location

The merchant must specify the location of the PayMaster Properties File using PropertiesReader.

Step 5 : Assign Values to PayMaster Request Entity

The merchant should assign values to the PayMaster Request Entity. The code must include all fields as specified in the sample code, as they are mandatory.

• The setter function is used to assign values and accepts two parameters: setter(parameter name, parameter value).

Step 6 : Call the Web Service Payment Request

Once all mandatory values are assigned, the merchant should call the Web Service Payment Request Message Builder with the buildUPPPaymentQueryRequest function.

• The Payment Query Request message will be generated and submitted to the PayMaster Gateway.
• The query response received from the PayMaster Gateway will be processed and assigned back to the PayMaster Request Entity.

Step 7 : Retrieve Values from PayMaster Request Entity

The merchant can use the same PayMaster Request Entity to retrieve information from the query response.

• The getter function is used to retrieve values and accepts one parameter: getter(parameter name).

Refer to UPP Payment Query Parameters for the fields supported by the PayMaster Merchant Plug-In (MPI).

Node.js

Step 1 : Library

The merchant must set up and include the PayMaster Merchant Plug-In (MPI) Node.js library in their application.

Step 2 : Source Code

const paymaster = require('./js/PayMaster.min.js');

module.exports = function (app) {
    app.get('/UPPQuery', (req, res) => {
        // Set values in PayMaster
        paymaster.setter('PaymentID', 'U02'); 
        paymaster.setter('MerchantID', '000010000099939'); 
        paymaster.setter('ServiceID', 'FNX'); 
        paymaster.setter('MerchRefNo', 'MYB2023030315435025LL'); 
        paymaster.setter('QueryRespURL', 'https://XXX.XXXXX.XXX/query.jsp');
        
        // Submit payment request to PayMaster
        paymaster.MERCH_UPPPaymentQueryRequest(paymaster.PaymasterRequestEntity, paymaster.propDetails, (err, response, result) => {
            if (err) {
                throw err;
            }
            if (response) {
                // Retrieve values from the response
                const MerchantID = paymaster.getter('MerchantID');
                const CardNo = paymaster.getter('CardNo');
                const TxnDtTm = paymaster.getter('TxnDtTm');
                const TxnAmt = paymaster.getter('TxnAmt');
                const TxnStatus = paymaster.getter('TxnStatus');
                const CurrCode = paymaster.getter('CurrCode');
                const AuthIDRespCode = paymaster.getter('AuthIDRespCode');
                const ExpTxnAmt = paymaster.getter('ExpTxnAmt');
                const RetrievalRefNo = paymaster.getter('RetrievalRefNo');
                const OrgRespCode = paymaster.getter('OrgRespCode');
                const OrigTxnAmt = paymaster.getter('OrigTxnAmt');
                const OrigCurrCode = paymaster.getter('OrigCurrCode');
                const TxnChannel = paymaster.getter('TxnChannel');
                const FICode = paymaster.getter('FICode');
                const PymtGwRefNo = paymaster.getter('PymtGwRefNo');
                const TxnStatDetCde = paymaster.getter('TxnStatDetCde');
                const TxnStatMsg = paymaster.getter('TxnStatMsg');
                const ServiceID = paymaster.getter('ServiceID');
                const MerchHostID = paymaster.getter('MerchHostID');
                const MerchSessionID = paymaster.getter('MerchSessionID');
                const MerchRefNo = paymaster.getter('MerchRefNo');
                const OrderRefNo = paymaster.getter('OrderRefNo');
                const QueryStatus = paymaster.getter('QueryStatus');
                const FPXRefNo = paymaster.getter('FPXRefNo');
                const UppPymtMode = paymaster.getter('UppPymtMode');
                const OrigRespCode = paymaster.getter('OrigRespCode');
                const ExporigTxnAmt = paymaster.getter('ExporigTxnAmt');
                
                // Send response
                res.json({
                    MerchantID,
                    CardNo,
                    TxnDtTm,
                    TxnAmt,
                    TxnStatus,
                    CurrCode,
                    AuthIDRespCode,
                    ExpTxnAmt,
                    RetrievalRefNo,
                    OrgRespCode,
                    OrigTxnAmt,
                    OrigCurrCode,
                    TxnChannel,
                    FICode,
                    PymtGwRefNo,
                    TxnStatDetCde,
                    TxnStatMsg,
                    ServiceID,
                    MerchHostID,
                    MerchSessionID,
                    MerchRefNo,
                    OrderRefNo,
                    QueryStatus,
                    FPXRefNo,
                    UppPymtMode,
                    OrigRespCode,
                    ExporigTxnAmt
                });
            }
        });
    });
} 

Step 3 : Indicate PayMaster Properties File Location

The merchant must specify the location of the PayMaster Properties File using PropertiesReader.

Step 4 : Assign Values to All Fields

The merchant must assign values to all fields as shown in the sample code.

• The setter function is used to assign values and accepts two parameters: setter(parameter name, parameter value).

Step 5 : Submit Payment Request to PayMaster

Use the MERCH_UPPPaymentQueryRequest()function to generate and submit the payment request message to PayMaster.

Step 6 : Response Parameters Returned by PayMaster

The response parameters returned by PayMaster will be processed by the PayMaster MPI Node.js library.

Step 7 : Retrieve Values of Payment Query Response Parameters

The merchant can retrieve the values of payment query response parameters using the getter function, which accepts one parameter: getter(parameter name).

Refer to UPP Payment Query Parameters for the fields supported by the PayMaster Merchant Plug-In (MPI).