Implementing a Hosted Payment Session Integration
In the Hosted Payment Session model, you present a payment form to the payer to collect the card details, which are then submitted directly from the payer's browser to the Mastercard Gateway. The gateway collects the card details in a session and temporarily stores them for later use. You can then include a session identifier in place of card details in the transaction request to process a payment.
Key benefits
- You do not handle or store any credit card details thereby lowering PCI compliance costs.
- You have full control of the branding and styling of payment pages.
- You can collect additional information on the payment form, for example, discount coupon code, loyalty program identifier, shipping address, shipping method, etc.
- You may use the additional information and card details collected to calculate the total payment amount. For example, your online shopping site could calculate:
- a surcharge depending on the card type used;
- freight based on the address and shipping method;
- a discount using the coupon code.
You can separate the initiation of payment from the collection of card details.
- You may integrate this solution with Tokenization thereby further reducing the scope and cost of a PCI DSS audit.
Prerequisites
- Ensure your merchant profile is enabled for API and Hosted Payment Session.
- Ensure connectivity to the Mastercard Gateway services.
- Before you commence integration, read the Best Practices and Tips section, below.
Best practices and tips
If a transaction is declined and you wish to offer the payer the option to try again then a new session must be created. The payment form must then be redisplayed to allow the payer to supply their card details.
Sessions expire after a number of hours. Any attempt to use a session that has expired will result in an error indicating that the session is invalid. The client application will be required to create a new session and collect the card details from the payer again.
A session may be updated with card details multiple times until it expires. You can use the session.version parameter to ensure that that the session information you are working with is the latest version.
Multiple operations may be performed using a single session once valid card details have been collected and added to it via the Payment Details Form. For example a Pay operation followed by a Tokenization operation. Note that the CSC will be dropped as soon as a financial transaction is performed (see below).
Card security codes are dropped from a session as soon as an operation referencing a session (except Open Wallet and Update Session) is performed. This is necessary to comply with PCI regulations. For example, if a Tokenization operation is performed using a nominal authorization, the card security code will be dropped and not included in the subsequent Pay operation.
Hosted Payment Session Implementation Model
The Hosted Payment Session solution supports two implementation models:
- Hosted Payment Session with JavaScript — this is the recommended integration method as it provides a quick and easy way to integrate client applications supporting JavaScript.
- Hosted Payment Session POST — use this if your client application does not support JavaScript.
Test and go live
Testing allows you to check if your integration is working as desired.
Troubleshooting and FAQs
The card details stored in the session may be updated until a Hosted Payment Session transaction is performed using the session. For example, if the payer wishes to update their card details because some of the details provided were incorrect then the card details may be updated before initiating a transaction to pay for the order.
If a transaction is declined and you wish to offer the payer the option to try again then a new session must be created. The payment form must then be redisplayed to allow the payer to supply their card details.
A payment session may be used in multiple transactions, for example, Pay followed by Save, until the session expires. However, it is important to understand that once a transaction has been performed for a session then the card details may no longer be updated. Therefore all transactions performed using the session will use the same card details.