Gateway-hosted Payment UI – MAP
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
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
“product”: “test order”,
Test using the form below:
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 >
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 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);