> ## 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.

# Checkout parameter reference

This page contains all available parameters and properties that you can use to initialize and customize Paybyrd Checkout.

***

## Query parameters

These parameters are part of the Checkout URL. Use them to generate and customize the payment gateway.

| **Parameter** | **Type**                             | **Required** | **Description**                                                                                                                 |
| ------------- | ------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `orderId`     | GUID                                 | Yes          | Identifies the order that the user sees during checkout. Generated during [order creation](/api-reference/orders/create-order). |
| `checkoutKey` | GUID                                 | Yes          | Identifies the checkout session that the user accesses. Generated during [order creation](/api-reference/orders/create-order).  |
| `configs`     | JSON object encoded to base64 string | No           | Enables further customization for the payment gateway. See [Checkout customization](/embed/checkout#how-to-integrate).          |

***

## Pathname properties

Set a display variant by adding it to the URL path between the domain and the query string. When not set, falls back to `default`.

| **Variant** | **Description**                                                                                                                             |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `default`   | Standard layout.                                                                                                                            |
| `detailed`  | Shows payment details and available methods on a single screen.                                                                             |
| `minimal`   | Recommended for iframes. Displays only the sections the user can interact with.                                                             |
| `immersive` | Based on `default` with an extra banner image at the top. Banner styles include airline, restaurant, marketplace, hospitality, and generic. |

```
https://chk.paybyrd.com/<variant>?checkoutKey=…&orderId=…&configs=…
```

**Examples**

* No variant (falls back to `default`): `https://chk.paybyrd.com/?checkoutKey=<…>&orderId=<…>&configs=<…>`
* `default`: `https://chk.paybyrd.com/default?checkoutKey=<…>&orderId=<…>&configs=<…>`
* `detailed`: `https://chk.paybyrd.com/detailed?checkoutKey=<…>&orderId=<…>&configs=<…>`
* `minimal`: `https://chk.paybyrd.com/minimal?checkoutKey=<…>&orderId=<…>&configs=<…>`
* `immersive`: `https://chk.paybyrd.com/immersive?checkoutKey=<…>&orderId=<…>&configs=<…>`

***

## Checkout customization parameters

Add these parameters to the `configs` object during initialization to further customize the checkout experience. The `configs` object should be **encoded to base64 format and then used as a query parameter in the checkout URL.**

Learn how to set these parameters in the [Checkout usage guide](/embed/checkout#how-to-integrate).

***

### `locale`

Sets the display language of Checkout. Defaults to `en-US` (English).

**Accepted values:** `en-US`, `en-UK`, `pt-PT`, `pt-BR`

| **Parameter** | **Type**      | **Required** | **Example value** |
| ------------- | ------------- | ------------ | ----------------- |
| `locale`      | string / enum | No           | `en-US`           |

***

### `logoUrl`

A URL pointing to your logo. Accepted file types are `JPG`, `PNG`, and `SVG`. Keep file sizes small to avoid slowing down page loads.

| **Parameter** | **Type**     | **Required** | **Example value**                   |
| ------------- | ------------ | ------------ | ----------------------------------- |
| `logoUrl`     | string / uri | No           | `https://domain.com/files/logo.png` |

***

### `hideLogo`

Controls whether your logo is visible to the end user within the payment gateway.

| **Parameter** | **Type** | **Required** | **Example value** |
| ------------- | -------- | ------------ | ----------------- |
| `hideLogo`    | boolean  | No           | `true` or `false` |

***

### `showHeader`

Show or hide the header. Defaults to `true`.

| **Parameter** | **Type** | **Required** | **Example value** |
| ------------- | -------- | ------------ | ----------------- |
| `showHeader`  | boolean  | No           | `true` or `false` |

***

### `showFooter`

Show or hide the footer. Defaults to `true`.

| **Parameter** | **Type** | **Required** | **Example value** |
| ------------- | -------- | ------------ | ----------------- |
| `showFooter`  | boolean  | No           | `true` or `false` |

***

### `showCancelButton`

Controls whether a **Cancel Payment** button is displayed. When clicked, the order status is set to Cancelled and the user is redirected to `redirectUrl`. Defaults to `false`.

| **Parameter**      | **Type** | **Required** | **Example value** |
| ------------------ | -------- | ------------ | ----------------- |
| `showCancelButton` | boolean  | No           | `true` or `false` |

***

### `showOrderSummary`

Controls whether an order summary screen is shown at the beginning of the payment process. Defaults to `true`.

| **Parameter**      | **Type** | **Required** | **Example value** |
| ------------------ | -------- | ------------ | ----------------- |
| `showOrderSummary` | boolean  | No           | `true` or `false` |

***

### `fullscreenModals`

When `true`, external modals such as 3DS checks or other MFA methods open in full screen. Defaults to `false`.

| **Parameter**      | **Type** | **Required** | **Example value** |
| ------------------ | -------- | ------------ | ----------------- |
| `fullscreenModals` | boolean  | No           | `true` or `false` |

***

### `defaultPaymentMethod`

Redirects the user directly to a predefined payment method on load. If the specified method is unavailable, the user sees the default payment method list.

When there is only one available payment method, Checkout automatically redirects to it and `defaultPaymentMethod` is ignored. When multiple methods are available, the user is redirected to the defined method and Checkout shows a back button so the user can select a different method.

Defaults to undefined.

**Accepted values:** `AMEX`, `APPLE`, `ELO`, `MASTER`, `MASTERDEBIT`, `MASTERCARD`, `PAYPAL`, `VISAELECTRON`, `VISADEBIT`, `VISA`, `DISCOVER`, `SIBS_MULTIBANCO`, `MULTIBANCO`, `SIBS_MBWAY`, `MBWAY`, `IDEAL`, `MAESTRO`, `CARTEBANCAIRE`, `DANKORT`, `DINERS`, `JCB`, `VPAY`, `SEPA`, `MULTICAIXA`, `MULTICAIXA_REF`, `MULTICAIXAEXPRESS`, `BANKTRANSFER`, `PICKUP`, `FLOA`, `FLOA3X`, `FLOA4X`, `FLOA1XD`, `PIX`, `REVOLUTPAY`, `SAMSUNGPAY`, `APPLEPAY`, `NUPAY`, `CREDITCARD`, `KLARNA`, `HIPERCARD`, `UNIONPAY`

| **Parameter**          | **Type**      | **Required** | **Example value** |
| ---------------------- | ------------- | ------------ | ----------------- |
| `defaultPaymentMethod` | string / enum | No           | `CARD`            |

***

### `redirectUrl`

The URL the user is redirected to after the payment is finished.

| **Parameter** | **Type**     | **Required** | **Example value**                       |
| ------------- | ------------ | ------------ | --------------------------------------- |
| `redirectUrl` | string / uri | Yes          | `https://domain.com/payment-validation` |

***

### `autoRedirect`

Controls whether the user is automatically redirected to `redirectUrl` after payment. When `false`, the user sees the Paybyrd payment validation page. Defaults to `false`.

| **Parameter**  | **Type** | **Required** | **Example value** |
| -------------- | -------- | ------------ | ----------------- |
| `autoRedirect` | boolean  | No           | `true` or `false` |

***

### `skipATMSuccessPage`

When `true`, redirects the user to `redirectUrl` instead of displaying the entity and reference values for ATM payments. Use this to handle the post-payment flow on your own side. Defaults to `false`.

| **Parameter**        | **Type** | **Required** | **Example value** |
| -------------------- | -------- | ------------ | ----------------- |
| `skipATMSuccessPage` | boolean  | No           | `true` or `false` |

***

### `skipMBWayWaitingForPaymentScreen`

Skips the polling screen shown while waiting for MB WAY payments. When `true`, the user is redirected to `redirectUrl` immediately. Defaults to `false`.

| **Parameter**                      | **Type** | **Required** | **Example value** |
| ---------------------------------- | -------- | ------------ | ----------------- |
| `skipMBWayWaitingForPaymentScreen` | boolean  | No           | `true` or `false` |

***

### `theme`

Controls the visual appearance of Checkout using hex color values. Pass this as a nested object inside `configs`.

| **Property**             | **Type**     | **Description**                                           |
| ------------------------ | ------------ | --------------------------------------------------------- |
| `backgroundColor`        | string (hex) | Page background color.                                    |
| `formBackgroundColor`    | string (hex) | Form container background color.                          |
| `primaryColor`           | string (hex) | Accent color for borders, input backgrounds, and buttons. |
| `textColor`              | string (hex) | Font color.                                               |
| `effectsBackgroundColor` | string (hex) | Effects layer background color.                           |

```json theme={null}
"theme": {
   "backgroundColor": "#F0F0F0",
   "formBackgroundColor": "#3C3C3C",
   "primaryColor": "#CCCCCC",
   "textColor": "#FFFFFF",
   "effectsBackgroundColor": "#DBDBDB"
}
```

***

**Usage example**

Form the URL using this pattern:

```json Example URL theme={null}
 https://chk.paybyrd.com/?checkoutKey={CHECKOUT_ID}&orderId={ORDER_ID}&configs={CONFIGS}
```

Where `{CONFIGS}` is a JSON object encoded to **base64 format**:

```json Raw JSON configuration theme={null}
{
   "redirectUrl":"https://your-site-url/payment-finished",
   "locale":"en_US",
   "theme":{
      "backgroundColor":"#F0F0F0",
      "formBackgroundColor":"#3C3C3C",
      "primaryColor":"#CCCCCC",
      "textColor":"#FFFFFF",
      "effectsBackgroundColor":"#DBDBDB"
   },
   "autoRedirect":true,
   "showCancelButton":false
}
```

```json Encoded to Base64 theme={null}
ewogICAicmVkaXJlY3RVcmwiOiJodHRwczovL3lvdXItc2l0ZS11cmwvcGF5bWVudC1maW5pc2hlZCIsCiAgICJsb2NhbGUiOiJlbl9VUyIsCiAgICJvcmRlcklkIjoiMTNhOGExNTctODFjOS00NmVhLTg0YjQtMmJlZjZkYWFkM2ZhIiwKICAgImNoZWNrb3V0S2V5IjoiZXlKUGNtUmxja2xrSWpvaU16RmhNRFl6TW1JdE9EY3hNeTAwTmpJd0xUaGlaakl0TURkaU4yVXlaVGs1TVRSaklpd2lUM0prWlhKU1pXWWlPaUkwTVRBeE1qQTNNVFUwSWl3aVVHVnljMjl1U1dRaU9qRXdMQ0pNYVhabElqcG1ZV3h6WlN3aVJXNTBhWFI1U1dRaU9pSXpNV0V3TmpNeVlpMDROekV6TFRRMk1qQXRPR0ptTWkwd04ySTNaVEpsT1RrZU5HTWlMQ0pCYlc5MWJuUWlPaUkxTUM0d01DSXNJa04xY25KbGJtTjVJam9pUlZWU0luMD0iLAogICAidGhlbWUiOnsKICAgICAgImJhY2tncm91bmRDb2xvciI6IiNGMEYwRjAiLAogICAgICAiZm9ybUJhY2tncm91bmRDb2xvciI6IiMzQzNDM0MiLAogICAgICAicHJpbWFyeUNvbG9yIjoiI0NDQ0NDQyIsCiAgICAgICJ0ZXh0Q29sb3IiOiIjRkZGRkZGIiwKICAgICAgImVmZmVjdHNCYWNrZ3JvdW5kQ29sb3IiOiIjREJEQkRCIgogICB9LAogICAiYXV0b1JlZGlyZWN0Ijp0cnVlLAogICAic2hvd0NhbmNlbEJ1dHRvbiI6ZmFsc2UsCn0=
```