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.
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:
Update a Session
You can add or update request fields in a session using:
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.
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]