> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paybyrd.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Migration guide
In a recent update, we have released a new version of Paybyrd’s payment gateway solution. Previously known as the Hosted Form, Paybyrd Checkout is now available for use. This update introduces new display functionality, a more streamlined payment flow, and several user experience improvements.
We have created this guide to help you migrate to the new version of Paybyrd Checkout.
To ensure that transition to the new version is seamless, Paybyrd continues to support implementations of the previous version for an indefinite period.
***
## List of changes
This section gives you a summary of the updates.
### Important changes
* The new version is now served through a different host URL. `checkout.paybyrd.com` changes to `chk.paybyrd.com`
* The payment gateway’s pathname is now formed differently. `/#/payment?checkoutKey=` changes to `/?checkoutKey=`
* A new request body parameter is now available for the `orderOptions` object in the [Create order endpoint](/api-reference/orders/create-order): `checkoutVersion`. This parameter enables you to set the version of Paybyrd Checkout that you want to generate for an order. Accepted values are:
* `1`: previous version
* `2`: new version
```json theme={null}
"orderOptions": {
"checkoutVersion": 2
},
```
* Checkout can now also support displaying external modals in full screen. When using the previous version within an iframe, any external modals that open up during the payment process were confined within the iframe. You can now define these to load in full screen. Examples include 3DSecure checks and other MFA methods that would open up in an external modal.
* Paybyrd Checkout now supports 4 different display variants: `default`, `detailed`, `minimal`, and `immersive`
* `default` is similar to the previous version.
* `detailed` shows a clear overview of the payment details and the available payment methods all within one screen.
* `minimal` is recommended for using in iframes. It focuses on only displaying sections that the user can interact with.
* `immersive` is based on `default` with an extra banner image at the top. Banner styles include airline, restaurant, marketplace, hospitality, and generic.
* You can set the display variant by adding a pathname property to the checkout URL. For example: `https://chk.paybyrd.com/detailed?checkoutKey=...`
***
### UX updates
* We have introduced an extra confirmation step in the payment process. This step gives end users a chance to confirm their selected payment methods before generating an order. The goal of this improvement is to eliminate user error by enabling end users to change their payment method selection.
* We have also added clear status messages and explanations so end users always know where they are within the payment process.
* Paybyrd now offers improved error messaging that show the cause of payment errors for specific payment methods.
* Checkout can now display extended information like flight or shopping cart details right within the landing page of the payment gateway.
### New and updated parameters
The new Checkout version now supports these parameters to customize the payment gateway:
**Set display variant**
Use this property in the pathname of the checkout URL to set a display variant.
| **Property** | **Type** | **Required** | **Example value** | **Description** |
| --------------------------------------------------- | -------- | ------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `https://chk.paybyrd.com/?checkoutKey=...` | pathname | No | `https://chk.paybyrd.com/detailed?checkoutKey=...` | Accepted values: `default`, `detailed`, `minimal`, `immersive`. When not set, falls back to `default`. |
**Customize UX**
Use these parameters to further customize the checkout experience. Learn how to set these parameters in the [Checkout guide](/embed/checkout).
| **Parameter** | **Type** | **Required** | **Example value** | **Description** |
| ---------------------------------- | ------------ | ------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `logoUrl` | string / uri | No | `https://domain.com/files/logo.png` | A URL pointing to your logo. Accepted file types are `JPG`, `PNG`, and `SVG`. Keep file sizes small to avoid slowing down page loads. |
| `hideLogo` | boolean | No | `true` or `false` | Controls whether your logo is visible to the end user. Defaults to `false`. |
| `showHeader` | boolean | No | `true` or `false` | Show or hide a UI section with your logo at the top. Defaults to `true`. |
| `showOrderSummary` | boolean | No | `true` or `false` | Controls whether an order summary screen is shown at the beginning of the payment process. Defaults to `true`. |
| `fullscreenModals` | boolean | No | `true` or `false` | When `true`, external modals such as 3DS checks or other MFA methods open in full screen. Defaults to `false`. |
| `skipMBWayWaitingForPaymentScreen` | boolean | No | `true` or `false` | Skips the polling screen for MB WAY payments. When `true`, the user is redirected to `redirectUrl` immediately. Defaults to `false`. |
See the [documentation](/embed/checkout-parameter-reference) for a complete list of parameters.
***
## Migrating to the new version
If you need support in migrating to the new version, reach out to the [Paybyrd operations team](mailto:help@paybyrd.com).
### 1. Define the version during order creation
To create a Checkout instance that uses the new version, add the `checkoutVersion` body parameter to the `orderOptions` object in your [Create order](/api-reference/orders/create-order) request, and set the value to `2`:
```jsx theme={null}
"orderOptions": {
... // other order options
"checkoutVersion": 2
},
```
This enables the Paybyrd API to return a `checkoutUrl` that points to the new version, using `chk.paybyrd.com` as the host URL.
You can then use the resulting checkout URL in your implementation when displaying the payment gateway.
### 2. Update URL references in your implementation
* When using an iframe to display the Paybyrd payment gateway, make sure you update the value of the `ENV_URL` constant to use the new host URL: `chk.paybyrd.com`
* When using a standalone link to direct the user to the payment gateway, make sure that you present a checkout URL that uses the new host URL: `chk.paybyrd.com`
Other methods, such as Pay by Link and PoS payments also use the new URL.
To ensure that transition to the new version is seamless, Paybyrd continues to support implementations of the previous version for an indefinite period.
If you do not want to update yet, set the `checkoutVersion` body parameter to `1` in the `orderOptions` object when you [Create an order](/api-reference/orders/create-order). This forces the Paybyrd API to provide a legacy checkout URL in the response, enabling your implementation to use the previous version of Paybyrd Checkout:
```json theme={null}
"orderOptions": {
... // other order options
"checkoutVersion": 1
}
```
Note that you will not be able to use any new features this way.