Capturing Payments Using Mastercard MIGS Service And ASP.NET Core

When the user completes the transaction, he will be navigated to,

https://localhost:44376/Home/PaymentCallback&vpc_Amount=121300&vpc_AuthorizeId=586587&vpc_BatchNo=20210129&vpc_CSCResultCode=M&vpc_Card=MC&vpc_Command=pay&vpc_MerchTxnRef=TX-1&vpc_Merchant=TESTEGPTEST&vpc_Message=Approved&vpc_OrderInfo=O-1&vpc_ReceiptNo=103006586587&vpc_TxnResponseCode=0&vpc_Version=1

No need for more explanation. The parameters are easy to understand and follow.

Ever wondered, what if a user simulates the payment process and just called the above URL of your site with any fake values?! Will you still count it as a valid transaction?

How do you differentiate between the true and fake responses? The answer is the integrity checking.

The last third in the secure credentials that we did not cover yet is the secure hash secret. This code is used to prevent the cardholder from modifying a transaction request and response when passing it though cardholder’s browser. This is what we call integrity checking.

Integrity checking works by using the hash secret code as a key to hash all our parameters and to send the generated hash along with our call to the server which in turn validates the hash and proceeds if valid. On the contrary, the server hashes all response parameters using the same hash secret code and returns the response along with the generated hash to our application, which we can validate by regenerating the hash and comparing it to the returned value.

Three things should be noted in this process,

1. VPC requires the hashed parameters to be ordered by ASCII ordinal values before hashing, e.g., the capital ‘E’ is before the small ‘a’.
2. VPC requires the usage of either HMAC SHA-256 or MD5 hashing algorithm.
3. The hash secret must be kept safe, it should not be exposed under any circumstances.

So, for this to work, we have two extra parameters that will be included in the request,

Parameter	Description
vpc_SecureHash	The generated hash.
vpc_SecureHashType	The hashing mechanism, which is ‘SHA256’ or ‘MD5’.

Let us see this in action.

For SHA-256 hashing you can use the following procedure for requests,

On the other hand, here is the response integrity checking mechanism for SHA-256.

For MD5 request hashes use the following procedure,

For response checking, use the following procedure,

Previously we have raised an issue about what will happen in server-hosted transactions if the user has closed the browser (for example) without returning to your site? The answer is in your unique merchant transaction number. You can use this number in the query API to query for transactions that has this number. That is why this number is strictly recommended to be unique.

The query command is based on the merchant-hosted model. And that means there will be no navigations, you will create the request and read its response instantly. It means also that it will use the vpcdps endpoint.

One critical thing to mention is that the transaction query command is part of the Advanced Merchant Administration (AMA) commands. Those advanced commands use an extra security credentials called the AMA username and password. Those credentials must be included as query parameters in the request.

For the transaction query request, we are going to use the following parameters,

Group	Parameter	Description
Common	vpc_Version	API version. Currently covered version is ‘1’.
vpc_Command	The command name, which will be ‘queryDR’.
Authentication	vpc_Merchant	Your merchant ID.
vpc_AccessCode	Your access code.
vpc_User	AMA username.
vpc_Password	AMA password.
Request Details	vpc_MerchTxnRef	Your unique transaction reference.

For the response, we are going to have the following parameters,

Parameter	Description
vpc_DRExists	Returns ‘Y’ if the requested transaction reference has been found.
vpc_FoundMultipleDRs	Returns ‘Y’ if there’s multiple transactions with the requested merchant transaction reference.
vpc_Amount	If one transaction found, we are going to have its amount here.
vpc_BatchNo	If one transaction found, we are going to have its batch number here.
vpc_TransactionNo	If one transaction found, we are going to have its unique transaction number here.

Here is a set of test credentials that can be used in the payment process. Normally you will receive your test credentials from your acquiring bank. You can also search the internet and get few test credentials like those.

Item	Value
Merchant ID	TESTEGPTEST
Access Code	77426638
Secure Hash	7E5C2F4D270600C61F5386167ECB8DA6

Here are a set of test cards that you can use,

Item	Card #1	Card #2
Type	Mastercard	Visa
Number	5123456789012346	4987654321098769
Expiry Date	05/21	05/21
Security Code	100	100

In this section we will go through the code very quickly.

Let us start with query parameters. To get our code generating parameters dynamically and to differentiate between parameter fields and other fields, we created an attribute that will be used to decorate only parameter fields.

Next, we started defining our class hierarchy and parameter properties,

We used reflection to get the parameter query properties and their corresponding values,

We used a simple code to generate and concatenate query strings,

And here is our secure hash generating code,

And the code to execute a merchant-hosted command is fairly straightforward,