Integration Types
Other Features
Card Payments
Mobile Wallets
Alternative Payment Methods
Resources
A payment session, or simply session, is a temporary container for any request fields and values of operations that reference a session. This allows you to use a session in an operation to reference the request fields and values rather than providing them directly in the operation request. When the Mastercard Gateway receives an operation that references a session, it forms the final request by combining the request fields in the session and those supplied directly in the request.
Using sessions enable more sophisticated integrations where different parts of the request are captured at different points in the payment flow or via different channels. For example, payment flows for both Hosted Session and wallets (for example, Masterpass) use sessions to collect and store sensitive payer information. This reduces PCI-compliance and implementation costs as you do not handle or store any payment details on your server.
As a first step, you must create a session, which you can then update with the request fields and values you wish to store in the session.
You can create a session using:
You can optionally provide the authentication limit (session.authenticationLimit), which indicates the number of operations which may be submitted to the gateway using the session id as a password. If not provided, the gateway sets a default value.
It returns the following fields:
session.id
: A unique session identifier which you must provide on subsequent requests to reference session contents.session.authenticationLimit
: The limit you supplied in the request or the gateway's default value.session.aes256Key
: The key you can use to decrypt sensitive data passed to your website via the payers's browser or mobile device.session.version
: You can use this field to implement optimistic locking of the session content.session.updateStatus
: A summary of the outcome of the last attempt to modify the session.session.js Reference[JavaScript]
You can add or update request fields in a session using:
It allows you to add payment and payer data into a session that can subsequently become the input to determine the risk associated with a payer in an authentication operation.
session.js Reference[JavaScript]
A session containing the request fields and values may be used in any of the following operations:
You may perform multiple operations using the same session, for example Pay and Tokenization. This is useful if you wish to perform a payment and also save the card details. Note that the API version for the operations referencing the session must match the API version used when updating or adding request fields to the session.
Open Wallet
, Update Session
, Update Session From Wallet
), the card security code, if stored in the session, is removed. This is necessary to comply with PCI regulations. If you want to save the card details for later use, you can do this by performing a Tokenization operation using the session.When submitting an operation request, the request fields and values stored against the session are used only if you do not provide them directly in the request.
You can obtain the request fields and values stored in a session by providing the session identifier.
If you make business decisions based upon data obtained from a session, you should use the optimistic locking capability of the session. This ensures that the data you used to make your decisions is the same as that used to process your request operation.
To use the optimistic locking capability you should:
Retrieve Session
operation.session.version
in the returned session contents.session.version
along with the session identifier as part of the operation.If the contents of the session have changed since you recorded session.version
, the gateway will reject the operation and return error.cause=INVALID_REQUEST
.
Examples of business decisions based on the session content include: