Payment Session

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

Key Benefits

Reduces PCI compliance costs as you do not handle or store any payment details.
Facilitates ease of integration as you do not need to directly handle the values for the request fields stored in a session.
Reduces internal fraud as your staff has limited access to payer's details.
Allows you to update the request fields and values stored against a session. This is useful when a credit card expires or other details of a payer change.
Allows you to retrieve the request fields and values contained in a session by specifying the session identifier.

Working with Sessions

Create a Session

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:

The Create Session call, which returns a unique session identifier that you must provide on subsequent requests to reference the session contents.
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.
Create Session API Reference[REST][NVP]
The Hosted Session service.
session.js Reference[JavaScript]

Update a Session

You can add or update request fields in a session using:

The Update Session call.

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.

Update Session API Reference[REST][NVP]
The Hosted Session service.
session.js Reference[JavaScript]
The Wallet services (Masterpass, Visa Checkout, Amex Express Checkout).
Update Session From Wallet API Reference [REST][NVP]

You cannot remove fields from a session but can only overwrite values for existing fields.

Use a Session

A session containing the request fields and values may be used in any of the following operations:

It is recommended that you retrieve the session details using the Retrieve Session operation and check the session contents before you initiate a payment or tokenization operation.

Verify[REST][NVP]
Pay[REST][NVP]
Authorize[REST][NVP]
Standalone Capture[REST][NVP]
Standalone Refund[REST][NVP]
Tokenization[REST][NVP]
Plan Offers Inquiry[REST][NVP]
Initiate Authentication[REST][NVP]
Authenticate Payer[REST][NVP]

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.

Once you initiate an operation that references a session (except 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.

Precedence Rules

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.

Retrieve Fields from a Session

You can obtain the request fields and values stored in a session by providing the session identifier.

Retrieve Session API Reference[REST][NVP]

Making Business Decisions Based on Session Content

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:

Securely retrieve the session contents using the Retrieve Session operation.
Record the value of session.version in the returned session contents.
Make your business decisions based on the returned session contents.
When you submit your request operation to the gateway, pass 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:

Calculating surcharge amount based on the card type provided by the payer.
Calculating shipping amount based on the shipping address provided by the payer.

Retrieve Session API Reference[REST][NVP]

Pay[REST][NVP]