# Hosted Session
source: https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-session/index.md

The Hosted Session integration method gives you control over the layout and styling of your payment page, while reducing PCI compliance costs.

The Session JavaScript library enables you to collect sensitive payment details from the payer in hosted payment form fields, sourced from, and controlled by the Mastercard Gateway. Standard browser security protection mechanisms isolate sensitive fields from you, preserving the integrity of the payment channel provided by the gateway. The gateway collects the payment details from the hosted fields in a payment session and temporarily stores them for later use. You can then include a payment session in place of payment details in your payment transaction request to process a payment.

For all initial transactions that require payer participation to provide their payment details, use the payment session to gather the payment details, and then send an API request from your server to initiate the payment transaction. For all merchant-initiated and subsequent transactions that do not require payer participation, send an API request from your server.

## Recommended paths {#recommended-paths}

Select the path that matches your role and integration requirements.

|                                 If you are a...                                  |                                         Then focus on...                                         |
|----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
| **Enterprise merchant**, a large merchant integrating directly with Gateway APIs | Accepting card payments from customers with the right balance of speed, control, and compliance. |
| **Software vendor**, an ISV embedding payment flows into platforms               | Enabling card payments for multiple merchants through a platform or product.                     |
| **Payment service provider**, a PSP, aggregator, or payment facilitator          | Processing and orchestrate card payments on behalf of many merchants.                            |

## API reference {#api-reference}

These APIs support the Hosted Session integration capabilities.

* [Session](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#session)

## API versions {#api-versions}

These version guidelines apply to the Hosted Session support in Mastercard Gateway.

|      If you need       |                                                               Then...                                                               |
|------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| To integrate to an API | Integrate with API version 100 for full compatibility. Hosted Session functionality is supported only from API version 18 or later. |

## Frequently asked questions {#frequently-asked-questions}

To handle this event, first use the [PAYMENT OPTIONS INQUIRY](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#gateway) operation to get a list of supported card types. Then inspect the card type information (`sourceOfFunds.provided.card.brand and sourceOfFunds.provided.card.scheme`) in the `PaymentSession.updateSessionFromForm('card')` response, validate it against the list of supported card types, and display an error message if the card type is not accepted. To find out whether CSC or CVV is required, use the [PAYMENT OPTIONS INQUIRY](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#gateway) operation. If the payer does not provide CSC/CVV, the `securityCode` field is NOT returned in the `PaymentSession.updateSessionFromForm('card')` response. If you require a CSC/CVV and no value is present, you need to display an error to the payer. There are known issues with event callbacks on the following operating systems and browsers:

* Internet Explorer 11 on Windows 10: If `interaction.displayControl.formatCard=EMBOSSED`, the `onChange()` event is not triggered when you change the value of a hosted field.
* iOS9 on iPhone 6+: The `onChange()` and `onBlur()` events are not triggered when the payer enters data in a hosted field and touches another field in the payment page. Further, the payer cannot navigate from hosted fields to other fields on the payment page or the reverse.

Alert: Hover events are not supported on touchscreen devices. When you do not receive a response, wait for 60 seconds and attempt to resubmit an identical request. If the gateway has received the original request and the new one is a duplicate, the bank transaction is not repeated, and no duplicate funds are transferred. You receive the same response as you would have received for the first request. All approved transactions are represented with a Transaction Response Code value of APPROVED from the gateway (see the `response.gatewayCode` field in your transaction response). Any other code represents a declined or failed transaction.

### Table: Hosted Session support {#table-hosted-session-support}

|                                 PCI Data Handling                                 |
|-----------------------------------------------------------------------------------|
| Hosted Session supports handling of PCI data sourced and controlled by Mastercard |
| Gateway such as cardholder, card, and account details.                            |

| Operations |
|------------|
| Authorize  |
| Pay        |
| Verify     |

To learn more about the Hosted Session integration model, review the following:

* To learn how sessions work in general, see [Payment Sessions](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-session/integrate-hosted-session/create-payment-session/index.md).
* To understand how to establish a session, add payment details to the session, send a payment request, and interpret the response, see [Integration Steps](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-session/integrate-hosted-session/index.md).
* To customize the Hosted Session user interface, see [Customizing the Hosted Fields](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-session/integrate-hosted-session/customize-hosted-fields/index.md).
* To find out how to use Hosted Session for follow-up transactions to execute complex payment scenarios, see [Subsequent Operations](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-session/integrate-hosted-session/subsequent-operations/index.md).
* For information on additional Hosted Session features, see [Features](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-session/integrate-gateway-features/index.md).

## Key benefits {#key-benefits}

The Hosted Session integration method has the following key benefits:

* Integration is simple and quick to implement.
* No need to collect, store, or process any sensitive payment details, thereby lowering PCI compliance costs.
* Maintain control over the styles and layout of your payment page.
* Customize the payer experience to suit your business.

## Information flow {#information-flow}

The payment flow for the Hosted Session integration method is illustrated below:
![](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/hostedSessionPaymentFlow.png)

The following steps describe the Hosted Session payment flow.

1. The payer initiates the payment process for goods or services in your app or web site.
2. The payer can choose to provide payments details using a [credit or debit card](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/cards/credit-debit-cards/index.md), [Click to Pay](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/click-to-pay/index.md), [gift card](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/alt-pay-methods/gift-cards/index.md), or to make an [Automated Clearing House](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/alt-pay-methods/a2a/ach/index.md) payment. Depending on the chosen payment method, payment details are collected in one of two ways:

* On your payment page: Payment details are collected in form fields embedded in iFrames, also known as inline frames, hosted by the gateway.
* Click to Pay: Card details are securely collected from the Click to Pay interaction and sent to the gateway.

3. The gateway collects the payments details and stores them in a [payment session](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-session/integrate-hosted-session/create-payment-session/index.md). When your server sends the payment request, you can simply reference the session. The payment transaction itself is handled similarly to the [Direct Payment](https://developer.mastercard.com/mastercard-gateway/documentation/build/direct-payment/index.md) integration method:  
   **a.** The gateway passes the transaction to your acquiring bank for processing.  
   **b.** The acquirer returns a response to the gateway.  
   **c.** The gateway generates a transaction response and passes it to you. The transaction response indicates if the transaction is successful, and allows you to display a receipt, other confirmation, or an error page to the payer.