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 Payment 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.


Best Practices and Tips

Handling Declined Transactions

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.

Session Expiry

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.

Collecting Card Details Multiple Times for a Single Session

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 on a Single Session

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 Code with the First Operation

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:

Test and Go Live

Testing allows you to check if your integration is working as desired.

Troubleshooting and FAQs

Can the card details be updated after submitting the Payment Form?

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.

What should I do if the payment (or save) operation is declined?

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.

Can I use the same payment session to perform multiple transactions?

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.

Copyright © 2023 Mastercard