Version info
Version 1.1
Overview
The MP Hosted Payment Page offers merchants an easy and convenient way to add a payment processing step to their web shop purchase flow. As HPP is hosted by MP, it allows merchants to process payments without the need to handle sensitive payment data.
A typical flow would involve a customer browsing the merchant's product catalog, adding items to a cart, entering shipping details, and proceeding to checkout. When a customer clicks the Pay button, the MP hosted payment page will be presented to the customer, where they can select a payment method and provide payment details. After the payment is completed, the customer is redirected back to the merchant's page.
With one simple HPP integration, the merchant gains support for multiple payment options.
How it works
To integrate HPP into a web shop, the merchant needs to follow several steps:
Firstly, the merchant should initiate a checkout session in the backend.
Redirect the customer to the HPP by utilizing the URL received from the MP in the checkout session response.
The customer will then proceed to complete the payment session and will be redirected back to the merchant's shop. In the backend, the merchant should verify the payment status.
Finally, the merchant should carry out any necessary post-payment actions, such as sending a confirmation email.
Step 1. Initiate a checkout session
A CheckoutStartSession service needs to be initiated in the merchant's backend. The service request must include mandatory data elements such as payment amount and currency. Additional information like customer details or shipping information may also be included, depending on the payment methods being used, as some payment methods require specific data.
Another important set of data elements are the return URLs, which are used to notify the web shop once the session has ended.
The response of CheckoutStartSession consists of two key data elements: a unique session ID and the HPP session URL. The web shop should store the HPP session ID in its own database. Normally, the web shop receives notifications when a session ends through the return URLs. However, there are instances where this may not occur, such as when a customer abandons the payment process or there is a loss of Internet connection. To ensure that the outcome is known even in these cases, the merchant can always request the session status from the MP using the session ID.
Below are examples of the CheckoutStartSession request and response. For a comprehensive specification, please refer to the API documentation.
REQUEST
POST /trx HTTP/1.1
Host: hpp2.prod.mpg.market-pay.com
<TRX>
<SVC>CheckoutStartSession</SVC>
<PRJ>EXAMPLE</PRJ>
<CTY>US</CTY>
<COM>Internet</COM>
<ORD>ORD45678901234567890</ORD>
<INV>INV45678901234567890</INV>
<CUR>USD</CUR>
<NET>900</NET>
<TAX>100</TAX>
<GRS>1000</GRS>
<SES>
<STY>https://example.com/myshop/checkout.css</STY>
<SUU>https://example.com/myshop/success</SUU>
<FAU>https://example.com/myshop/failure</FAU>
<CVI>Required</CVI>
<ACT>Capture</ACT>
</SES>
</TRX>RESPONSE
HTTP/1.1 200 Ok
<SES>
<SID>RM9VDJFCWSUC5</SID>
<SST>Created</SST>
<SEU>
https://hpp2.prod.mpg.marketpay.com/hppv22/checkout.hpp?sessionId=RM9VDJFCWSUC5
</SEU>
</SES>Step 2. Forward a customer to hosted payment page
After starting checkout session in merchant’s backend, web shop needs to present HPP page to the customer using HPP session URL received in the response. There are couple of ways to show HPP to the customer.
Option 1: open HPP in iframe
Incorporating an iframe into a web shop page is one of the methods used to present the HPP to customers. Adding an iframe is a straighdorward process: simply insert an HTML inline frame element at the appropriate position on the page.
EXAMPLE
<html>
<body>
. . .
<iframe src=
”https://hpp2.prod.mpg.marketpay.com/hppv22/checkout.hpp?sessionId=RM9VDJFCWSUC5” >
</iframe>
. . .
</body>
</html>The value of the "src" attribute should be set to the session URL received in the CheckoutStartSession response.
When adding an iframe, it is important to consider the "width" and "height" attributes. These should be selected to ensure that the frame is adequately sized to accommodate the content of all relevant payment forms, while maintaining the desired font sizes.
Since the HPP displays payment options in collapsible accordions, the content's height changes based on customer actions. To address this, a JavaScript code can be implemented in the web shop to adjust the height of the inline frame dynamically.
EXAMPLE
<script>
/* <![CDATA[ */
var old_height;
function receiveMessage(event) {
// Get the height from the passsed data.
var h = Number( event.data.substr( 11 ) ) + 25;
if ( !isNaN( h ) && h > 100 && h !== old_height ) {
// Height has changed, update the iframe.
$("#hpp").height( old_height = h );
}
}
$(window).on("message", function(e) {
receiveMessage(e.originalEvent);
});
/* ]]> */
</script>Option 2: open HPP in full page mode
If the merchant intends to launch the Hosted Payment Page (HPP) in a full browser window rather than within an inline frame, it is indeed possible. To achieve this, the merchant can simply redirect the customer to the HPP session URL.
Step 3. Check payment status
After MPG completes payment processing, the customer is redirected to one of the return URLs provided in the CheckoutStartSession. Depending on the payment outcome the customer is redirected either to a success, failure, or cancellation URL.
The merchant should use the MPG service to check the payment status. The response will include the payment transaction ID, which can be utilized for further processing, such as canceling the payment if necessary.
REQUEST
GET /ses/RM9VDJFCWSUC5?view=status HTTP/1.1
Host: hpp2.prod.mpg.market-pay.comRESPONSE
HTTP/1.1 200 Ok
<SES>
<SID>RM9VDJFCWSUC5</SID>
<SST>Completed</SST>
<SPM>
<SPI>N83A66RWMFAW1</SPI>
<MPY>VISA</MPY>
<CRD>
<SCN>****0000</SCN>
<EXP>1115</EXP>
</CRD>
<GRS>1000.00</GRS>
<NET>900.00</NET>
<TAX>100.00</TAX>
</SPM>
<TRX>
<XID>MPR6HLBCVVDC1</XID>
<CUR>USD</CUR>
<NET>900.00</NET>
<TAX>100.00</TAX>
<GRS>1000.00</GRS>
<MPY>VISA</MPY>
<CRD>
<SCN>****0000</SCN>
<EXP>1115</EXP>
</CRD>
</TRX>
</SES>The GetSessionStatus service can be invoked as frequently as required by the merchant. It is also advisable to check the status of payment sessions where the redirection to the return URL did not occur due to technical issues, such as the customer losing internet connection after a successful payment.
For a comprehensive specification of the GetSessionStatus service, please refer to the API documentation.
Customization
Merchants have the option to customize the appearance of the hosted payment page by specifying a stylesheet URL within the CheckoutStartSession service. The customized stylesheet for merchants should exclusively contain elements that require modification, while the remaining elements will retain their styling as per the default stylesheet of the Market Pay Hosted Payment Page.
Merchants can tailor the design of payment sections, payment summaries, buttons, fonts, colors, and apply diverse styling rules to HTML elements.
For detailed guidance on styling, please refer to Customization guides.
Payment error handling and resuming session
If a transaction error occurs during the payment processing, the HPP redirects the customer to the merchant's designated failure URL. At this point, the merchant has the ability to check the session status and determine the appropriate course of action. Depending on the error type, the merchant may have the option to resume the session.
If the session is in a "SoftFailed" status, the merchant can restore the session by accessing the same URL provided in the initial CheckoutStartSession response. This allows the customer to retry the payment, such as by selecting a different payment option or entering a different card number.
However, for certain error types, the HPP does not permit the merchant to resume the session. In these cases (like indications of suspected fraud), the session status is updated to "HardFailed," and the transaction is considered complete. If the merchant wishes to allow the customer to make another payment attempt, a new CheckoutStartSession must be initiated.
See different session statuses in the table below:
Session status | Description |
|---|---|
Created | Indicates that the session has been successfully initiated. |
Completed | Indicates that the session has been successfully completed. The payment process has been finalized, and the session cannot be used anymore. |
Expired | Indicates that the session has expired due to inactivity for more than 15 minutes. This is a security measure. An expired session cannot be resumed or utilized any longer. |
Canceled | Indicates that the customer has canceled the session. This typically occurs when the customer presses the "Cancel" button on the Hosted Payment Page. |
SoftDeclined | Indicates a non-severe error has occurred. SoftDeclined sessions can be resumed by accessing the original session URL returned in the CheckoutStartSession response. There is no limit to the number of times a SoftDeclined session can be resumed. |
HardDeclined | Indicates a severe error has occurred. This session status is only set when fraud is suspected. It can be triggered if the bank response indicates a stolen card or similar issues, or when the MPG risk manager detects fraudulent payment method data. HardDeclined sessions cannot be resumed or utilized any longer. |
Redirection and destroying an iframe
If an inline frame is used to integrate HPP into the web shop, several additional steps need to be taken on a web shop page to handle the redirect to the return URL correctly.
When the payment session ends, MPG will notify the merchant web shop of the payment status by posting the session ID to a return URL specified in CheckoutStartSession. Since this post occurs across different domains, it is always done with the target="_self" attribute to comply with security requirements. Consequently, the merchant's return URL will open inside the inline frame, and the content of the return URL's response will be displayed within the inline frame.
The merchant has a few options for the next steps:
Option 1: Add a form with the target="_parent" attribute and submit the form using JavaScript. This will automatically navigate the customer to a new web shop page without requiring any action.
EXAMPLE
<html>
<head>
<script type="text/javascript">
setTimeout('document.forms.redirectForm.submit()', 0);
</script>
</head>
<body>
<form method="post" id="redirectForm" action="/shop/success.faces"
target="_parent">
<input type="hidden" name="sessionId" value="<%=
request.getParameter("sessionId") %>">
<noscript>
<div>Please click the button below to continue</div>
<input type="submit" value="Continue">
</noscript>
</form>
</body>
</html>Option 2: Receive a message from the inline frame and navigate the customer to a new web shop page. This option utilizes the JavaScript postMessage mechanism. Once the payment is completed, the inline frame will send a postMessage to the parent window. The parent window captures the message and performs the redirection. The supported post messages are: payment_success, payment_failure, payment_cancel, and payment_review. The following is an example of the JavaScript code on a web shop page that captures these messages and performs the redirect.
EXAMPLE
<script type="text/javascript">
// Called on message event
function receiveMessage(event) {
// Notice that script should be called after an iframe is part of your
DOM.
$('iframe').ready(function() {
var data = event.data;
9
// These statuses are sent by the payment iframe as a reaction
// Perform the redirection depending on the status using JavaScript
window.location.
if (data == 'payment_success') {
window.location = 'your.success.url';
return;
} else if (data == 'payment_cancel') {
window.location = 'your.cancel.url';
return;
} else if (data == 'payment_failure') {
window.location = 'your.failure.url';
return;
} else if (data == 'payment_review') {
window.location = 'your.review.url';
return;
}
});
}
// Receive message event
$(window).on("message", function(e) {
receiveMessage(e.originalEvent);
});
</script>Option 3: Display confirmation text in the inline frame to the customer and prompt them to click on a button to navigate to a new web shop page.
Hosted wallet management page
The guidelines for hosted payment page integration can also be applied to integrate the hosted wallet management page. Instead of invoking the CheckoutStartSession service, the merchant should call the ProfileStartSession service and utilize the URL received in the response to display the wallet management page for the customer.
The hosted wallet management page enables customers to add, update, or delete payment instruments in their wallet. These payment instruments will be presented to customers during the checkout process, enabling them to complete payments with just a single click.
For a comprehensive specification of the ProfileStartSession service, please refer to the API documentation.
Google PayTM as a payment option
This section outlines specific requirements for merchants looking to integrate Google Pay as a payment option.
Branding
When a merchant mentions Google Pay as a payment option, such as in their Terms and Conditions (T&Cs), the first or most prominent occurrence must include the trademark symbol (TM).
Merchants wanting to display the Google Pay logo to signify support for this payment option should adhere to the Google Pay Web Brand Guidelines.
Implementation Paths
Market Pay is hosting Google Pay payment button on behalf of their merchants; there are no other ways currently to integrate Google Pay and support Android or Web merchants.
Merchants must create a checkout session following the instructions in the integration guide, loading the HPP URL in an iframe or a new window. If Google Pay is enabled, the Market Pay HPP will handle rendering it as a payment option.
To enable Google Pay, a specific configuration must be added during the onboarding process. Contact your representative to activate Google Pay.
Market Pay's Google Pay SDK, operating in HPP, generates IsReadyToPayRequest and PaymentDataRequest properties for the merchant. Supported payment options, like VISA or Mastercard, are set based on the merchant's configured payment options. For example, if a merchant has configuration to support VISA and MASTERCARD as payment options in the card payment forms, these payment options will be set as the allowed card networks for Google Pay as well. No additional configuration is required on the merchant's side.
Merchants must comply with the Google Pay APIs Acceptable Use Policy and accept the terms defined in the Google Pay API Terms of Service.
Implementation Details
Market Pay will conduct a 3DS check with the card selected from the Google Pay wallet. The merchant's configuration will be set up as PAN_ONLY, and there's no need for the merchant to provide this detail in any request.
Merchants do not need to obtain merchant IDs from Google; Market Pay generates IDs for them. here's no requirement for merchants to provide gateway (value is set up to ‘marketpay’ by Market Pay) or gatewayMerchantID (this is an id that uniquely identifies you within the gateway and is set up by Market Pay) in any request.
There are no specific requirements regarding BillingAddressParameters for the merchants. Merchants submit billing addresses in the CheckoutStartSession request and this data for AVS checking and for processing.
Merchants are not required to send encrypted payment data and transaction data to Market Pay servers; this data is directly retrieved by Market Pay from Google.
The list of card networks Market Pay supports is listed here.
Additional Information