# Migrate to Hosted Session version 100
source: https://developer.mastercard.com/mastercard-gateway/documentation/tutorials-and-guides/migration-guides/mig-hosted-session-v100/index.md
## Migrate Create Checkout Session {#migrate-create-checkout-session}
Warning: version/62/merchant/{merchantId}/session Create checkout session is deprecated after version 62 and should be migrated to [Hosted Checkout](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-checkout/index.md):[Initiate Checkout](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#hosted-checkout).
## Migrate Retrieve Session to version 100 {#migrate-retrieve-session-to-version-100}
Warning: version/100/merchant/{merchantId}/session/{sessionId} Migration guide for `Session-RetrieveSession` from version 18 to 100.
## Breaking changes {#breaking-changes}
### Structural changes in 3DSecure fields {#structural-changes-in-3dsecure-fields}
| Field | Version 18 | Version 100 | Breaking? |
|------------------------------------|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------|
| `3DSecure.` | Present as a top-level group | Replaced by `authentication.3ds`, `authentication.3ds1`, `authentication.3ds2` | Yes --- structure and naming changed |
| `3DSecure.authenticationRedirect.` | Present | Replaced by `authentication.redirectResponseUrl` and others | Yes --- renamed and restructured |
| `3DSecure.authenticationStatus.` | Present | Replaced by `authentication.3ds2.transactionStatus` and `authenticationStatus` | Yes --- renamed and moved |
| `3DSecure.authenticationToken.` | Present | Now under `authentication.3ds.authenticationToken` | Yes --- moved and renamed |
| `3DSecure.xid` | Present | Now `authentication.3ds.transactionId` | Yes --- renamed |
| `3DSecureId` | Present | Instead of using `3DSecureId`, the gateway uses `authentication.transactionId`. This new ID refers to the authentication that happens at the start of an order. So, authentication is no longer treated as a separate step, it is now considered the first part of the order. | Yes --- removed |
### New fields {#new-fields}
| Field | Condition | Breaking? |
|--------------------|--------------------------------------------------------------|-----------------------------------|
| `accountFunding.*` | Required for account funding transactions | Yes --- new conditional structure |
| `agreement.*` | Required for recurring, installment, or unscheduled payments | Yes --- new conditional structure |
| `debtRepayment.*` | Required for debt repayment transactions | Yes --- new conditional structure |
| `authentication.*` | Required for 3DS2 and payer authentication | Yes --- new structure |
## Payload comparison {#payload-comparison}
The payload comparison fields or groups are not backward compatible and may require implementation changes.
| Field/Group | Version 18 | Version 100 | Notes |
|---------------------------------------------|-------------|-------------|-----------------------------------------------------------------------------------------------|
| cruise | Not present | Present | Cruise industry-specific fields added |
| `authentication.3ds2` `authentication.psd2` | Not present | Present | Full 3DS2 support added in v100 |
| `appPayment` | Not present | Present | Manage interactions with the payment provider if you are offering your payment page in an app |
| `customer.account` | Not present | Present | New in version 100 for account-level metadata |
| `accountFunding` | Not present | Present | New in version 100 for account-to-account transfers |
| `cardBin` | Not present | Present | New in version 100 for BIN-level logic |
| `browserPayment` | Not present | Present | New in version 100 for browser-based wallet flows |
| `creditCardBillPayment` | Not present | Present | New in version 100 for credit card bill payments |
| constraints | Not present | Present | New in version 100 for payment plan constraints |
| agreement | Not present | Present | New in version 100 for recurring or installment agreements |
| `authorizationResponse` | Not present | Present | New in version 100 for standalone capture responses |
## Response format changes {#response-format-changes}
For the Retrieve Session API response comparison between version 18 to version 100, see the [changelog](https://gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/100/changelog.html?locale=en_US).
## Migrate Update Session to version 100 {#migrate-update-session-to-version-100}
Warning: version/100/merchant/{merchantId}/session/{sessionId} Migrate the Hosted Session:UpdateSession from version 18 to 100.
### Breaking changes {#breaking-changes-1}
| Field/Group | Version 18 | Version 100 | Notes |
|----------------------------------|------------------------|------------------------------------------------------------------------|------------------------------------------|
| `3DSecure.acsEci` | Present under 3DSecure | Moved to `authentication.3ds.acsEci` | Restructured under authentication object |
| `3DSecure.authenticationToken` | Present | `authentication.3ds.authenticationToken` | Field renamed and nested |
| `3DSecure.xid` | Present | `authentication.3ds.transactionId` | Renamed for clarity |
| `3DSecure.authenticationStatus` | Present | `authentication.3ds1.authenticationStatus` or `3ds2.transactionStatus` | Split by 3DS version |
| `3DSecure.enrollmentStatus` | Present | `authentication.3ds1.enrollmentStatus` | Version-specific nesting |
| `3DSecureId` | Present | `authentication.3dsId` | Renamed and relocated |
| `billing.address` | Basic structure | Includes `stateProvinceCode`,`countrySubdivision` and so on | More granular address fields |
| `shipping.address.sameAsBilling` | Not available | Available | New boolean field |
| `authentication.channel` | Not present | Required for 3DS2 | New required field |
## Payload comparison {#payload-comparison-1}
| Field/Feature | Version 18 | Version 100 | Notes |
|-------------------------------------|-----------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Endpoint Version | /version/18/... | /version/100/... | Updated version path |
| 3DSecure Fields | Present | Present | Full support for 3DS2, including: - `authentication.3ds2.sdk`, `authentication.3ds2.transactionStatus`, `authentication.3ds2.protocolVersion` - `authentication.psd2.exemption` for PSD2 compliance |
| Airline Data | Present | Present | Extended in v100 |
| Billing and Shipping Info | Present | Present | v100 adds more granular fields |
| Order Details | Present | Present | Version 100 includes more optional fields like `discount`, `statementDescriptor`, `subMerchant` and so on |
| Transaction Info | Present | Present | v100 adds `authorizationAdjustmentActions`, `deferredAuthorization`, and so on |
| Source of Funds | Present | Present | v100 supports more payment types. For example, Klarna, PayPal, Apple Pay, and so on |
| Authentication | Present | Present | v100 supports 3DS1, 3DS2, and PSD2 exemptions |
| Session Versioning | Not present | `session.version` | Enables optimistic locking |
| Agreement Object | Not present | Present | For recurring, installment, or unscheduled payments |
| Account Funding and Debt Repayment | Not present | Present | Version 100 supports account-to-account transfers New `accountFunding` and `debtRepayment` objects for P2P and financial institution use cases |
| Cruise Industry Data | Not present | Present | Version 100 supports cruise-specific fields |
| Browser and Device Info | Basic | Extended | Version 100 adds `device.browserDetails` includes screen size, color depth, JavaScript support, and so on, for 3DS2 risk-based authentication |
| Risk Assessment Fields | Basic | Extended | Version 100 includes `risk.custom`, `risk.paymentRecipient`, and so on |
| Sub-Merchant and Aggregator Support | Not present | Present | Version 100 supports marketplaces and sub-merchants |
| Payment Plan and Installments | Basic | Extended | Version 100 adds `paymentPlan.offerId`, `constraints.paymentPlans`, and so on |
| Digital Wallets and Tokenization | Basic | Extended | Version 100 supports Apple Pay, Google Pay, PayPal, and so on |
| Error Handling | Basic | Enhanced | Version 100 adds `error.field`, `error.validationType` |
## Response format changes {#response-format-changes-1}
For the Update Session response comparison between version 18 to version 100, see the [changelog](https://gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/100/changelog.html?locale=en_US).
## Migrate Create Payment Page session {#migrate-create-payment-page-session}
Warning: version/26/merchant/{merchantId}/session Hosted Session: `CreatePaymentPageSession` is deprecated after version 26 and should be migrated to [Hosted Checkout](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-checkout/index.md):[Initiate Checkout](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#hosted-checkout) version 100.
### Migrate Authorize with Session {#migrate-authorize-with-session}
Warning: version/3/merchant/{merchantid}/order/{orderid}/transaction/{transactionid} Hosted Session: `AuthorizeWithSession` is deprecated after version 3 and should be migrated to [Transaction:Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) version 100.
### Migrate Create Session to version 100 {#migrate-create-session-to-version-100}
Warning: version/100/merchant/{merchantId}/session Migrate the Create Session from version 2 to version 100 of the `CreateSession` API.
### Breaking changes {#breaking-changes-2}
##### Endpoint and authentication changes {#endpoint-and-authentication-changes}
| Change | Version 2 | Version 100 | Action required |
|-----------------------|-------------------------------|-----------------------------------------|------------------------------------------|
| API Endpoint | /version/2/session | /version/100/session | Update endpoint in all API calls |
| Authentication Format | Basic Auth with blank user ID | Basic Auth with `merchant.` | Update credentials format in integration |
##### Structural and field-level changes {#structural-and-field-level-changes}
| Field Version 2 | Version 100 | Action required | |
|-------------------------------|---------------|-----------------|-----------------------------------------------|
| `session.authenticationLimit` | Not available | Present | Optional: Set limit on session usage |
| `session.aes256Key` | Not available | Present | Optional: Use for decrypting sensitive data |
| `session.updateStatus` | Not available | Present | Optional: Use for decrypting sensitive data |
| `session.version` | Not available | Present | Optional: Use for optimistic locking |
| `lineOfBusiness` | Not available | Present | Optional: Specify business line if applicable |
##### Validation and error handling enhancements {#validation-and-error-handling-enhancements}
| Field | Version 2 | Version 100 | Action required |
|------------------------|---------------|-------------|------------------------------------------------------|
| `error.field` | Not available | Present | Update error handling to parse field-specific errors |
| `error.validationType` | Not available | Present | Handle new validation types like MISSING, INVALID |
## Payload comparison {#payload-comparison-2}
| Field/Feature | Version 2 | Version 100 | Notes |
|------------------------------------------------|--------------------------|-----------------------|------------------------------------------------------------------|
| Endpoint Version | /version/2/... | /version/100/... | Updated version path |
| Purpose | Hosted Payment Form only | Full payment session | v100 supports broader use cases |
| `correlationId` | Optional | Optional | No change |
| `session.authenticationLimit` | Not present | Optional and Returned | Limits number of operations using session ID |
| `session.aes256Key` | Not present | Returned | AES key for decrypting sensitive data |
| `session.updateStatus` | Not present | Returned | Indicates if the session was successfully updated |
| `session.version` | Not present | Returned | For optimistic locking of session content |
| `lineOfBusiness` | Not present | Optional | Supports multi-business configurations |
| merchant | Returned | Returned | No change |
| [`session.id`](https://www.sessionstudio.com/) | Returned | Returned | No change |
| `result` | Returned | Returned | No change |
| Error Handling | Basic | Enhanced | Version 100 adds field and `validationType` for better debugging |
## Response format changes {#response-format-changes-2}
For the Create Session response comparison between version 18 to version 100, see the [changelog](https://gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/100/changelog.html?locale=en_US).
### Migrate Pay with Session {#migrate-pay-with-session}
Warning: version/3/merchant/{merchantid}/order/{orderid}/transaction/{transactionid} Hosted Session: Pay With Session is deprecated after version 3 and should be migrated to [Transaction: Pay v100](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction).
### Migrate Save Card, with system-generated token, with Session {#migrate-save-card-with-system-generated-token-with-session}
Warning: version/3/merchant/{merchantid}/order/{orderid}/transaction/{transactionid} Hosted Session: `SaveCardWithSession`(token) is deprecated after version 3 and should be migrated to [Tokenization: Create or Update Token version 100](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#tokenization).
### Migrate Save Card with Session {#migrate-save-card-with-session}
Warning: version/3/merchant/{merchantid}/order/{orderid}/transaction/{transactionid} Hosted Session: `SaveCardWithSession` is deprecated after version 3 and should be migrated to [Tokenization: Create or Update Token version 100](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#tokenization).