Gateway-hosted Payment UI – MAP

You are here:
← All Topics

 

In the MAP Payment UI gateway-hosted model, the consumer is directed to the our payment page to complete the payment transaction.

The advantage of this method is that merchant do not need to worry about handling and transmitting consumer card details. This helps to reduce risk on merchant.

Merchant also do not need to implement payment flow and confirmation which will be handled by MC Payment.

 

Payment flow (3DS)

The image below illustrates the payment flow for transactions performed on MAP Payment UI for 3D Secure Transactions. Click on image to enlarge.

 

Payment flow (without 3DS)

The image below illustrates the payment flow for transactions performed on MAP Payment UI. Click on image to enlarge.

How is 3DS transaction decided?

The first step to determine if transaction will be 3D secure is that the “mid” parameter is being validated if it is enabled for 3DS processing. Next, our gateway will check if the card being used in the transaction is enrolled for 3DS. If the first two conditions passed, the transaction will be processed as 3D secure, in which, the user will be redirected to the card issuer’s (bank) OTP page to authenticate his transaction. The merchant is still able to process a transaction even if the card is not enrolled for 3DS, as long as there is sufficient credit. This entire process is handled by our payment gateway, therefore merchant need not implement. It is important to note that with 3DS processing, the merchant liability is greatly reduced in case of chargeback or dispute.

How to send a payment request

Send the request data as specified in the Request Parameters table below via https with “POST”. This can be achieved, for example, by using HTML form or code.

Request URL: ​https://map.sandbox.mcpayment.net/payment/dopayment

Request Parameters

*Note:

1 – Parameter names have to be written lower case alphabet.
2​ – If parameter values include special characters, please use “URLEncoder.encode” and “URLDecoder.decode”.
3​ – M: Mandatory.
4 – O: Optional.

Sample JSON Request

{
“mid”: “3118080001”,
“reference”: “220720191719”,
“cur”: “SGD”,
“txntype”: “SALE”,
“shop”: “testshop”,
“buyer”: “mynameis”,
“email”: “sales@mcpayment.com”,
“product”: “test order”,
“amt”: “1.00”,
“fgkey”:”1f5f04ddc415476f5458d4553de9b439″,
“cardno”: “4111111111111111”,
“cvv”: “111”,
“expmonth”: “12”,
“expyear”: “2020”,
“cardholder”: “mynameis”,
“tokenize”: “N”,
“frequency”: “”
}

Test using the form below:





Click the button to continue to payment page


 

Implementation notes

statusurl​ is main callback handler. It triggers first and postback full data package about the payment. System sends it in background. No page will be opened for it. Please implement database update logic in this callback handler only.

returnurl ​is auxiliary callback handler. After end of the payment process system redirects payer to this url. Use data provided to show basic info about the payment to payer. Please do not use this url for database update. Otherwise, if payer will close the page, your database will be not updated and you will lose the transaction.

We strictly recommend to implement both callback url handlers: ​resulturl​ and ​statusurl. ​Otherwise we do not guarantee postback data (payment result) delivery.

For both callback handlers read POST data ($_POST array in php) only. GET url data is deprecated and will be removed.

Analyze ​rescode​ in the callback handlers. Payment could be considered successful if rescode=​0000​. In all other cases error occurred. Validate response fgkey if rescode == “0000” only.

​FgKey generation rules Purpose of fgkey validation is to ensure if response data wasn’t changed by fraud. See MD5 Hashing.

For test cards, get the details here >

Response Parameters

 

List of Response Codes and Messages

Important note for Rejected transactions (error code 2090): For detailed info, please login to the merchant portal. Example of detailed info includes: insufficient credit, lost card, etc.

MD5 Hashing

MD5 hashing is an encryption method that ensures that URLs have not been manipulated or changed. This allows the integrity of the link in a data exchange between two parties to be checked.

MD5 is an abbreviation for “Message Digest Algorithm 5” and is a widely used cryptographic hash function.
This length of the hash value produced by this hash function is 128 bits. The hash value is returned as a 32-digit hexadecimal number, which look like this: ​34048ce4cd069b624f6e021ba63ecde5

How it works
MD5 should always be used when you want to request every link. The MD5 verifies the integrity of the URL of the MCP link entered by comparing the new MD5 sum with a previously established sum. This way, it can be determined whether the URL has been changed. The primary purpose of this is to prevent the manipulation of data.

Setting up the MD5 hashings
MD5 requires a secret key which you approve. This key will be saved by your account support manager in the service area. You must then use this key to form a hash and build it into the MCP link.

Hashing via the merchant
In order to access the MCP link so-called “fgkey”, which contains the MD5 hash and is assigned as a parameter in MCP link, is required. The fgkey is generated by the “dynamic secret key(dynkey)” and MCP link inclusive “mid”, “reference” or “ref”, “cur”, “amt” parameters. In case of response, inclusive “mid”, “reference” or “ref”, “cur”, “amt”, “rescode”, “transid” parameters. (​The order of parameters is important​.)

Sample of how fgkey is generated in php:

$linkBuf = $secretKey. “?mid=” . $mid .”&ref=” . $ref .”&cur=” .$cur .”&amt=” .$amt;
$fgkey = md5($linkBuf);

If you have any questions regarding this API, contact our Technical Support Team >

Company
Merchant
Resources
Connect with us
Privacy Settings
We use cookies to enhance your experience while using our website. If you are using our Services via a browser you can restrict, block or remove cookies through your web browser settings. We also use content and scripts from third parties that may use tracking technologies. You can selectively provide your consent below to allow such third party embeds. For complete information about the cookies we use, data we collect and how we process them, please check our Privacy Policy
Youtube
Consent to display content from Youtube
Vimeo
Consent to display content from Vimeo
Google Maps
Consent to display content from Google