Please note this content is awaiting translation.
Migrate to Hosted Session version 100
Migrate Create Checkout Session
version/62/merchant/{merchantId}/session
Create checkout session is deprecated after version 62 and should be migrated to Hosted Checkout:Initiate Checkout.
Migrate Retrieve Session to version 100
version/100/merchant/{merchantId}/session/{sessionId}
Migration guide for Session-RetrieveSession from version 18 to 100.
Breaking changes
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
| 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
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
Fot the Retrieve Session API response comparison between version 18 to version 100, see the changelog.
Migrate Update Session to version 100
version/100/merchant/{merchantId}/session/{sessionId}
Migrate the Hosted Session:UpdateSession from version 18 to 100.
Breaking changes
| Field/Feature | 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
| 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:
|
| 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 | NEnables 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 suppor 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
For the Update Session response comparison between version 18 to version 100, see the changelog.
Migrate Create Payment Page session
version/26/merchant/{merchantId}/session
Hosted Session: CreatePaymentPageSession is deprecated after version 26 and should be migrated to Hosted Checkout:Initiate Checkout version 100.
Migrate Authorize with Session
version/3/merchant/{merchantid}/order/{orderid}/transaction/{transactionid}
Hosted Session: AuthorizeWithSession is deprecated after version 3 and should be migrated to Transaction:Authorize version 100.
Migrate Create Session to version 100
version/100/merchant/{merchantId}/session
Migrate the Create Session from version 2 to version 100 of the CreateSession API.
Breaking 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.<merchantId> | Update credentials format in integration |
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
| 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
| 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 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 | 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
For the Create Session response comparison between version 18 to version 100, see the changelog.
Migrate Pay with Session
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 .
Migrate Save Card, with system-generated token, with Session
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.
Migrate Save Card with Session
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.