Session Basics
A payment session, or simply session, is a temporary container for request fields containing sensitive data about a specific order. You can use a session to allow the payer to provide their sensitive payment details directly to the Mastercard Gateway. This way you can simply reference the session in any later transaction request, without having to handle the payment details directly. When the Mastercard Gateway receives a transaction request that references a session, it forms the final transaction by combining the fields in the session with those supplied directly in the request.
Using sessions enables more sophisticated integrations where different parts of the request are captured at different points in the payment flow or through different channels. For example, payment flows for both the Hosted Session and some payment methods, for example, ClickToPay, use sessions to collect and store sensitive payer information. This reduces PCI compliance requirements and implementation costs as you do not handle or store any payment details on your server.
The lifecycle of a single session covers:
- Creating the session in your server.
- Updating the session in your server with any non-sensitive information you want to store in the session.
- Using the session on your web site or app to allow the gateway to gather any sensitive payment details from the payer.
- Referencing the session in payment transactions or other operations in your server.
A single session lasts usually about 15 minutes, during which you can send one or more payment transactions, as needed.
Creating a session
You can create a session using the Create Session operation. In the request, you can optionally provide the authentication limit (session.authenticationLimit), which indicates the number of operations which can be submitted to the gateway using the session ID as a password. If the limit is not provided, the gateway sets a default value. You can use the session ID as a password in requests that use session authentication. Session authentication allows you to make API requests directly from your app or web site (instead of your server), and can be used for 3D Secure authentication requests.
The CREATE SESSION operation returns the following fields:
- session.id - Unique session ID which you must provide on subsequent requests to reference the session.
- session.authenticationLimit - Limit you supplied in the request, or the gateway’s default value.
- session.aes256Key - Key you can use to decrypt sensitive data passed to your web site through the payer's browser or mobile device.
- session.version - Session version. You can use this field to implement optimistic locking of the session content.
- session.updateStatus - Summary of the outcome of the last attempt to modify the session.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/session |
| HTTP Method | POST |
{
"session": {
"authenticationLimit": 25
}
}
Updating a session
You can add or update request fields in a session using the Update Session operation. 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.
Alternatively, you can update a session using the UPDATE SESSION FROM WALLET operation with ClickToPay.
- When updating a session, you cannot remove fields from it, you can only overwrite the values for existing fields.
- The UPDATE SESSION operation can be used in your server to add fields to the session. To add sensitive payment information to a session (by allowing the payer to provide them directly to the gateway), you must use hosted fields on your payment page. For more details on how to handle the hosted fields within the session, see Making a Payment.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/session/<session_ID> |
| HTTP Method | PUT |
{
"order": {
"amount": 100,
"currency": "USD"
}
}
Using a session in a payment transaction
After you have added all the relevant fields to the session (directly from your server or using hosted fields on your payment page), you can refer to that session in any of the following operations by using the session.id field:
- It is recommended that you retrieve the session details using the Retrieve Session transaction and check the session contents before you initiate a payment or Tokenization operation.
- When you refer to a session in an operation request, if a value for the same field is provided both in the referred session and in the operation request itself, the value in the operation request is used. For more information, see Multiple Payment Data Sources.
- Verify
- Pay
- Authorize
- Standalone Capture
- Standalone Refund
- Create or Update Token
- Payment Options Inquiry
- Initiate Authentication
- Authenticate Payer
You can perform multiple operations using the same session, for example PAY and CREATE OR UPDATE TOKEN. This is useful if you want to both initiate a payment and store a token to use in future payments.
Making business decisions based on session content
If you make business decisions based upon data obtained from a session, you need to use the optimistic locking capability of the session. This ensures that the data you use to make your decisions is the same as that used to process your request operation.
- Calculating surcharge amount based on the card type provided by the payer.
- Calculating shipping amount based on the shipping address provided by the payer.
To use the optimistic locking capability:
- Retrieve the session content using the RETRIEVE SESSION operation.
- Take note of the session.version value in the response.
- Make the business decisions, as needed.
- Send your operation request to the gateway and include the session.version value along with the session ID in the request.
If the session content has changed, the session.version in your request does not match the current version and the gateway rejects the operation with error.cause=INVALID_REQUEST.