Integration Steps
To implement the basic Hosted Session solution in your system, follow the instructions below.
Prerequisites
Before implementing a Hosted Session solution, check with your payment service provider to ensure you meet the following prerequisites:
- Ensure that you have a merchant account and that your merchant profile is enabled for the Hosted Session service.
- Select and set up your API authentication method.
- We recommend integrating with API version 100 for best results and future support. Hosted Session supports any version later than 18.
Implementing a Hosted Session Integration
The Hosted Session solution works through API operations (requests and responses), which are used to, for example, manage sessions and initiate or retrieve information about various payment transactions. You also need the Session JavaScript library to manage the hosted payment form fields in your app or web page, when payer participation is needed to gather payment details for a transaction. For more information about handling sessions, see Payment Sessions.
You can use all the API operations available for the REST Server APIs. However, you do not need the Hosted Checkout-related API operations, as they are required for the related integration method.
For more information about making server API requests, see Making a Server API Request.
When payer participation is needed, each task you perform with the Hosted Session integration method consists of the following steps:
- In your server, create a new session as a container for all the sensitive data required by the transaction.
- In your app or web site, attach the hosted form fields to your payment page and allow the payer to fill them in.
- In your app or web site, update the session with the provided data.
- In your server, send a payment transaction request to the gateway, referring to the session.
- In your server, retrieve the response data from the payment transaction. Interpret the response and display the transaction result to the payer in your app or web site.
For information on handling steps 1-4 above, see Making a Payment. For information about handling the transaction result, see Interpreting the Response.
For a collection of example requests covering the common transaction operation requests, download the Postman collection.
After your integration is completed and you are able to manage basic requests and responses:
- Consider your payment lifecycles and needs for any subsequent operations after the basic payment transaction is completed.
- Determine any customizations you need to make based on the specific payment methods you want to support.
- Consider what kind of security or other additional features you want to offer or use in your integration.
- Test your entire solution.
Hosted form fields
To attach the hosted form fields to your payment page using Mastercard GatewayHosted Session, use the PaymentSession.configure() function provided by Mastercard's JavaScript SDK.
Follow these steps to attach the hosted form fields:
- Include the Mastercard Hosted Session Script.
- Replace <your_merchant_id> and <version> with your actual values.
- Configure the Hosted Fields Use PaymentSession.configure() to attach the hosted fields to your HTML form.
- Mastercard hosts secure iFrames that replace the fields you specify.
- You must create a session through the API before calling configure().
- The API version used in the session creation must match the version in the script URL.