Implementing a Hosted Payment Page Integration

This page documents a legacy feature. The Hosted Payment Page protocol has been deprecated by the Hosted Checkout JavaScript integration. More information about how to obtain the payment result and further customize your integration can be found on the Hosted Checkout page.

The Hosted Payment Page model allows you to collect payment details from your payer through a web page hosted and displayed by the MasterCard Payment Gateway thereby managing security and PCI-compliance for you. With this model of integration, you never see or handle payment details directly because the payment details collected on the payment page are submitted directly from the payer's browser to the MasterCard Payment Gateway.

Request a Payment Page

You request the Hosted Payment Page by sending a HTTPS POST request to the MasterCard Payment Gateway. This step is critical in the merchant integration as the data in your request determines the content displayed to the payer on the payment page.

The HTTPS POST request can contain any of the fields described in the Hosted Payment Page API Reference. Please ensure that you include all the required fields in your request.

Sample code for a basic Hosted Payment Page integration is shown below:

<form method="post" action="https://ap-gateway.mastercard.com/api/page/version/36/pay">

<input type="hidden" name="merchant" value="<your_merchant_id>"/>
<input type="hidden" name="order.amount" value="100.00"/>
<input type="hidden" name="order.currency" value="USD"/>
<input type="hidden" name="order.description" value="37 Blue Widgets"/>
<input type="hidden" name="interaction.merchant.name" value="My Merchant Name"/>
<input type="hidden" name="interaction.cancelUrl" value="http://www.mymerchant.com"/>
<input type="submit" value="Checkout"/>
</form>

Point interaction.cancelUrl to a URL to which you want the payer's browser to be redirected to if they cancel their payment. This could be a link back to the payer's shopping cart, or the home page of your shop site.

It is recommended that you include the order.id field in your request to easily identify a payment initiated from the Hosted Payment Page. You can use an identifier generated by your shopping cart or supply your own; however, ensure that it is unique. If you don't supply a value in the order.id field, the MasterCard Payment Gateway will automatically generate one for you.

By default, your merchant configuration determines the functionality offered on the payment page to your payer. For example, payment methods (credit cards, PayPal, etc), transaction sources (Internet, call Centre, etc), payment options (payment plans), 3-D Secure service, risk management, etc.

Testing your integration

Before going live, you must test your integration to ensure correct functionality.

Copyright © 2021 MasterCard