---
title: "Checkout Toolkit Integration"
source_url: https://docs.rapyd.net/en/checkout-toolkit-integration.html
lang: en
---

# Checkout Toolkit Integration

A checkout solution without the PCI-DSS compliance worry.

### Create Your Own Customized Page

Checkout Toolkit has been specially designed to embed directly into your shopping cart payment fields to give your business more control over the entire checkout experience.

> **Note:**
>
> Looking for a quick start? This  [tutorial](https://community.rapyd.net/t/how-to-build-a-hosted-checkout-page-and-embed-a-checkout-toolkit/1699) will walk you through the steps of building a hosted checkout page with Rapyd Checkout and then embedding it in your website using Rapyd’s Checkout Toolkit.

### How to Integrate Checkout Toolkit

[Companion Code Sample for Video: Checkout Toolkit Demo](https://github.com/Rapyd-Samples/checkout-toolkit-demo)

### Supported End-User Devices

The following end-user devices are supported:

| Device | Description |
| --- | --- |
| Mobile Phone Browsers | Width is responsive and is supported from 320px onwards. For optimal readability, define the screen width. The height size is dynamic and changes according to the content.  **Note: Do not set a limit on the height.** |
| Desktop Browsers | Supports a width of 500px and above. The height size is dynamic and can change according to the content.  **Note: Do not set a limit on the height.** |

### Steps for Creating Your Checkout Page

Before embedding the iframe into your page, refer to [Hosted Checkout Page Integration](https://docs.rapyd.net/en/hosted-checkout-page-integration.md "Hosted Checkout Page Integration") and follow steps 1 and 2 to create your Checkout Page.

Once you create the Checkout page, in the response to the Create Checkout Page, you’ll receive the ID of the checkout page object, a string starting with  `checkout_`, (for example: id: "checkout_9ebe58dcb9d75e8f972a35350f96c2fa").

> **Note:**
>
> You need to specify **one** payment method type category in the Create Checkout request, or alternatively, **one** payment method type or **one** list of payment method types of the same category.

Add the following code to your checkout page:

1. Add a <script> tag with the URL of the Rapyd Checkout Toolkit:

   ```
   <script src="https://checkouttoolkit.rapyd.net"></script>
   ```

   > **Note:**
   >
   > To run this method in the  [sandbox](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_sandbox "Sandbox"), use the following code:

   ```
   <script src="https://sandboxcheckouttoolkit.rapyd.net"></script>
   ```
2. Add a <div> tag with id="rapyd-checkout":

   ```
   <div id="rapyd-checkout"></div>
   ```
3. Initialize the Checkout Page object with the following fields:

   - - JavaScript

       - ```javascript
         Instantiating ‘checkout’ with parametersInstantiating 'checkout' & setting variables
         let checkout = new RapydCheckoutToolkit({
             pay_button_text: "Click to pay",
                   // Text that appears on the 'Pay' button. 
                   // String. Maximum length is 16 characters.
                   // Default is "Place Your Order". Optional. 
             pay_button_color: "blue",
                   // Color of the 'Pay' button. String.
                   // Standard CSS color name or hexadecimal code such as #323fff.
                   // Default is the color that is returned in the 'merchant_color'
                   // field of the response to 'Create Checkout Page'. Optional.
             id: "checkout_9ebe58dcb9d75e8f972a35350f96c2fa",
                   // ID of the 'Create Checkout Page' response. String. Required.
             wait_on_payment_confirmation: false,
                   // Default is 'false'. Optional. 
                   // You can keep the Toolkit open in a pending state. 
                   // The iframe will close when the payment session has been completed. 
                   // The timeout is set to 10 minutes.
             wait_on_payment_redirect: false,
                   // Default is 'false'. Optional.
                   // The iframe will close when the payment session has been completed.
                   // The user will redirect to complete the 3DS Verification. 
             hide_submit_button: false, 
                   // Default is 'false'. Optional. 
                   // The submit button will not be visible if set to 'true'. (See CHECKOUT_SUBMIT_PAYMENT event). 
                   // This is relevant only for the Checkout Toolkit (not other toolkit solutions). 
             close_on_complete: true,
                   // Causes the embedded Rapyd Checkout Toolkit window to close
                   // When the payment is complete. Boolean. Default is 'true'. Optional.           
             page_type: “collection”
                  // Default is "collection". Optional.
         });
         ```
4. Call display Checkout() to display the checkout page.

   ```
   checkout.displayCheckout();
   ```
5. Optional step. If `close_on_complete` is set to false, call `checkout.closeCheckout()` to close the Rapyd Checkout Toolkit window.

   ```
   checkout.closeCheckout();
   ```
6. Optional Step. You can pass the  `hide_submit_payment` field as 'true' in order to hide the submit payment button created by the Rapyd Checkout Toolkit. Then, by triggering the  `CHECKOUT_SUBMIT_PAYMENT` event, you can manage the submit button. Relevant only for Checkout Toolkit.

   - - JavaScript

       - ```javascript
         const iframeElement = document.getElementById('rapyd-checkout-frame');
         iframeElement.contentWindow.postMessage({type: "CHECKOUT_SUBMIT_PAYMENT"}, '*');
         ```
7. Insert your code that runs when the following events occur. Use your code to read the event field in the  **window** object.

   - - JavaScript

       - ```javascript
         window.addEventListener('onCheckoutPaymentSuccess', (event) => {
                             console.log(event.detail)
                             // Returns 'Payment' object.
                             // Client code.
         })
                     
         window.addEventListener('onCheckoutPaymentFailure', (event) => {
                             console.error(event.detail.error)
                             // Returns an error message from the API.
                             // Client code.
         })
                     
         window.addEventListener('onLoading', (event) => {
                             console.log(event.detail.loading)
                             // returns true or false depending on the loading state
                             // client code
         })
                     
         window.addEventListener('onCheckoutPaymentPending', (event) => {
                             console.log(event.detail)
                             // Returns 'Payment' object.
                             // Client code.
         })

         window.addEventListener('onCheckoutPaymentExpired', (event) => {
                             console.error(event.detail.error)
                             // Returns a constant error message
                             // The event is triggered when the payment status is 'EXP'. 
                             // "CHECKOUT_PAYMENT_EXPIRED"
         })
           

         window.addEventListener('onCheckoutUpdateCardSuccess', (event) => {
                             console.log(event.detail)
                             // Returns payment method object. 
                             // client code
         })
                     
         window.addEventListener('onCheckoutDeleteCardSuccess', (event) => {
                             console.log(event.detail)
                             // Returns deleted payment method object.
                             // client code
         ```

### Sample Embedded Rapyd Checkout Toolkit

Here's an example of a Rapyd Checkout page created using the Toolkit:

- - HTML

    - ```html
      HTML
      <!DOCTYPE html>
      <html>

      <head>
          <meta http-equiv="content-type" content="text/html; charset=utf-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title>Rapyd Checkout Toolkit</title>
          <script src="https://checkouttoolkit.rapyd.net"></script>
          <script>
              window.onload = function () {
                  let checkout = new RapydCheckoutToolkit({
                      pay_button_text: "Click to pay",
                      pay_button_color: "blue",
                      id: "checkout_9ebe58dcb9d75e8f972a35350f96c2fa"
                  });
                  checkout.displayCheckout();
              }
              window.addEventListener('onCheckoutPaymentSuccess', function (event) {
                  console.log(event.detail)
              });
              window.addEventListener('onCheckoutPaymentFailure', function (event) {
                  console.log(event.detail.error)
              });
          </script>
      </head>

      <body style="background-color: #f1f1f1; display: flex; align-items: center; flex-direction: column; margin: 0">
          <h1>Rapyd Checkout Toolkit Demo</h1>
          <div style="width: 500px" id="rapyd-checkout"></div>
      </body>

      </html>
      ```

On successful payment, the clients receive a  `onCheckoutPaymentSuccess` event with the payment object.

Note the following fields and the tasks associated with each of them.

Payment Object Fields

| Field | Description | Action |
| --- | --- | --- |
| status | Indicates the status of the payment (Read-only).  Responses - (One of the following):  - **ACT** - Active and awaiting payment. Can be updated. - **CAN** - Canceled by the merchant or the customer's bank. - **CLO** - Closed and paid. - **ERR** - Error. An attempt was made to complete the payment, but failed. - **EXP** - The payment has expired. | You can use this field to check the payment status, whether it is active, awaiting completion, or closed and paid. |
| redirect_url | Third party URL where the customer is supposed to complete the payment, for example: card payments with 3DS authentication, bank redirect payments, redirect to eWallets. | - When the payment status is **ACT** and a URL is returned in the redirect_url field, make sure to redirect the customer to this URL. - When this payment is completed, the customer is redirected to the URL that you provided in complete_payment_url or error_payment_url. |
| instructions | Describes the required steps that the customer should take for completing the payment. (Read-only). | When the payment status is  **ACT** and instructions are provided, you can display them to the customer. |
| textual_codes | A text code or a set of text codes for the customer to use to complete the steps described in the instructions field. (Read-only). | When the payment status is  **ACT** and textual_codes are provided, display them along with the key and value to the customer. |
| visual_codes | An image or a set of images for the customer to use to complete the steps described in the instructions field, for example, a QR code or barcode. (Read-only). | When the payment status is  **ACT** and visual_codes are provided, display them along with the key and value to the customer.  1. If the value is a URL, display the URL as an image. 2. If the value is base 64, display the image. |

**Recommendation**: Be sure to implement navigation elements (e.g. back, return, or cancel) on your website when embedding the Toolkit Integration solution.

### Checkout Toolkit Customizations

You can use the toolkit to tailor your Checkout page according to your preference.

### Digital Wallet Buttons

A parameter called `digital_wallets_buttons_only` has been added to the Checkout Toolkit. The default value is `false`. If the default value is set to `true`, then buttons will appear in the Hosted Checkout Page that will allow you to link to digital wallets such as Google Pay and Apple Pay.

An array called `digital_wallets_include_methods` has been added. You can specify the following values: `google_pay` or `apple_pay`. The value you pass will determine the payment method used for the button. **Default**: both.

An object called `digital_wallets_buttons_customization` has been added, and contains the following objects and parameters:

- `button_style` - an object that contains the configuration for each digital wallet type. For Apple Pay, the following values are: `black`, `white`, or `white-outline`. **Default**: black.

  For Google Pay, the following values are: `black` or `white`. **Default**: black.
- `button_type` - allows the merchant to specify the wording of the button. For Apple Pay, the following values are: `add-money`, `book`, `buy`, `check-out`, `contribute`, `donate`, `order`, `plain`, `reload`, `rent`, `subscribe`, `support`, `tip`, `top-up`. **Default**: buy

  For Google Pay, the following values are: `book`, `buy`, `checkout`, `donate`, `order`, `pay`, `subscribe`. **Default**: buy

**Note**: For more information, refer to the [Apple Pay](https://applepaydemo.apple.com/apple-pay-js-api) and [Google Pay](https://developers.google.com/pay/api/web/guides/resources/customize) user documentation.

Use the following code example to create the digital wallet buttons using the toolkit:

- - JavaScript

    - ```javascript
      let checkout = new RapydCheckoutToolkit({
          pay_button_text: "Click to pay",   // Max 16 characters
          pay_button_color: "blue",           // CSS color or hex
          id: "checkout_b0d925ac8612bb417c227f0ae73447a4",  // Your actual checkout page ID
          close_on_complete: true,            // Close checkout window after payment
          page_type: "collection",            // Optional, default is "collection"
          digital_wallets_buttons_only: true,
          digital_wallets_include_methods: ["google_pay", "apple_pay"],
          digital_wallets_buttons_customization: {
              google_pay: {
                  button_color: "black",
                  button_type: "book"
              },
              apple_pay: { 
                  button_color: "black",
                  button_type: "book"
              }
          }
      ```

### Translations

You have the option of changing the default language of your payment page to any of the currently available languages in the list below:

|  |  |  |
| --- | --- | --- |
| Simplified Chinese | Traditional Chinese | English |
| Estonian | German | Greek |
| Hindi | Icelandic | Indonesian |
| Italian | Japanese | Korean |
| Bahasa Malayu (Malaysian) | Lithuanian | Russian |
| Portuguese | Slovak | Slovenian |
| Spanish | Thai | Turkish |
| Tagalog | Ukrainian | Vietnamese |
| Danish | Hebrew | Polish |
| Swedish | Czech | Latvian |
| Maltese | Norwegian |  |

Specify it in the language parameter field when generating the Checkout page.

**Note**: See the full list of languages at [Hosted Page Language Support](https://docs.rapyd.net/en/localization-methods.md "Localization Methods").

### Pending Status for the Checkout Toolkit

You can pass the `wait_on_payment confirmation` field as 'true' to keep the iframe open in a pending state. The  `onCheckoutPaymentPending` event is triggered, which returns the payment object. The user is redirected to a **pending** status page while they complete their payment. Pay codes or instructions are displayed if they are present in the payment object.

The **pending** status page has a default timeout of 10 minutes. The iframe is then closed and the  `onCheckoutPaymentExpired` event is triggered if the payment is not completed within that timeframe.

The merchant can pass the `payment_expiration` parameter for the [Create Checkout Page](https://docs.rapyd.net/en/create-checkout-page.md "Create Checkout Page") request to shorten the 10 minute payment timeframe.

**Note:** Do not set a limit on the height.

### 3DS Authentication Redirect

You can pass the `wait_on_payment_redirect` field as 'true' to apply a checkout experience for card payments with 3DS verification included. The `onCheckoutPaymentPending` event is triggered, which returns the payment object. The user is redirected and completes the 3DS verification.

The iframe closes when the `onCheckoutPaymentSuccess` event is triggered when the payment is completed, or if the  `onCheckoutPaymentFailure` event is triggered if the payment is incomplete or an error is encountered.

### Custom CSS

### Elements

The table below lists all the available elements:

Description of Body Parameters

| Body Parameter | Description |
| --- | --- |
| tooltip | Tooltips, used for displaying extra information about certain fields, e.g. CVV Code in card payments |
| submit | Submit button |
| input | Input fields |
| dropdown | Drop down lists |
| clear | Clear button, used for clearing the input in input fields and drop down lists |
| global | An element designed for general configurations  **Note**: See below for more details |

### Global Elements

- **fonts** array: global.fonts is an array of custom fonts, which can hold either a url or an object, as seen in the example below. The family set in global.fonts can be used in the fontFamily CSS property.

- - CSS

    - ```
      global = {
        fonts: [
          "https://fonts.googleapis.com/css2?family=Mulish:wght@200&amp;display=swap",
          {
            family: 'myCustomFont',
            src: '/fonts/myCustomFontRegular.woff2',
            fontWeight: 400
          },
          {
            family: 'myCustomFont',
            src: '/fonts/myCustomFontBold.woff2',
            fontWeight: 700
          }
        ]
      }
      ```

- **fontSizes**: the configured sizes apply to all the texts in Checkout Toolkit. You can override the global.fontSizes by configuring fonts per element. The fontSizes supports every CSS unit, (for example, rem, px).

> **Note:**
>
> - We recommend using rem units, to keep the app responsive to all device sizes (as the UI is designed on rem units).
> - Rapyd's UI is based on a root font-size of 10 pixel (1 rem = 10px).

### Variants and States

Every element can be configured with one or more of the following variants or pseudo-classes and pseudo-elements:

| Variants and States | Decription | Elements that it applies to |
| --- | --- | --- |
| placeholder | Applied to the element's placeholder | - input - dropdown |
| disabled | Applied when the element is disabled | - input - dropdown |
| hover | Applied when the element is in a hover state | - dropdown - submit - clear - button - tooltip content |
| active | Applied when the element is in an active state | - input - dropdown - submit - clear - tooltip button |
| error | Applied when the element is in an error state | - input - dropdown |
| focus | Applied when the element is in focus while navigating a web page using the TAB key (or equivalent) | - input - dropdown |
| selection | Applied to a selected text within an element | - input |
| item | Applied to all the items in a drop down field | - dropdown |
| list | Applied to the full list in a drop down field | - dropdown |
| base | The default style | - input - dropdown - submit - clear - tooltip button - tooltip content |

### CSS Properties

Each specified property name must be in camel case, for example, borderRadius not border-radius.

### Toolkit Default Theme and Available CSS Properties

- - CSS

    - ```
      const defaultTheme = {
        "global": {
          "fonts": [],
          "fontSizes": {
            "extraSmall": "1.2rem",
            "small": "1.4rem",
            "medium": "1.6rem",
            "large": "2rem",
            "extraLarge": "4rem"
          },
        "input": {
          "base": {
            "borderColor": "#e9ecef",
            "backgroundColor": "#fff",
            "borderRadius": "4px",
            "color": "#1a1a1a",
            "fontSize": "1.4rem",
            "fontWeight": 500,
            "fontFamily": ""
          },
          "active": {
            "borderColor": "#0046ff",
            "backgroundColor": "",
            "color": "",
            "labelColor": "#0046ff"
          },
          "error": {
            "borderColor": "#ff3650",
            "backgroundColor": "",
            "color": "",
            "labelColor": "#ff3650"
          },
          "focus": {
            "outline": "none"
          },
          "placeholder": {
            "fontSize": "1.4rem",
            "fontWeight": 500,
            "color": "#9ba2a7",
            "fontFamily": ""
          },
          "selection": {
            "color": "",
            "backgroundColor": ""
          },
          "disabled": {
            "backgroundColor": "#fbfbfb",
            "color": ""
          }
        },
        "cardFields": {
          "title": {
            "color": ""
          },
          "saveForFutureLabel": {
            "color": ""
          }
        },
        "requiredFields": {
          "title": {
            "color": ""
          }
        },
        "orderDetails": {
          "title": {
            "color": ""
          },
          "totalLabel": {
            "color": ""
          },
          "totalValue": {
            "color": ""
          }
        },
        "pciMessage": {
          "color": ""
        },
        "dropdown": {
          "backgroundColor": "",
          "title": {
            "color": ""
          },
          "base": {
            "fontSize": "1.4rem",
            "fontWeight": 500,
            "color": "#1a1a1a",
            "borderColor": "#e9ecef",
            "backgroundColor": "#fff",
            "borderRadius": "4px",
            "fontFamily": ""
          },
          "active": {
            "borderColor": "#0046ff",
            "backgroundColor": "",
            "color": ""
          },
          "error": {
            "borderColor": "#ff3650",
            "backgroundColor": "",
            "color": "#ff3650"
          },
          "focus": {
            "outline": "none"
          },
          "placeholder": {
            "fontSize": "1.4rem",
            "fontWeight": 500,
            "color": "#000",
            "fontFamily": ""
          },
          "disabled": {
            "color": "#9ba2a7",
            "backgroundColor": "#fbfbfb"
          },
          "item": {
            "transition": "0.3s",
            "base": {
              "backgroundColor": "#fff",
              "color": "#1a1a1a",
              "fontFamily": ""
            },
            "active": {
              "backgroundColor": "#e9ecef",
              "color": ""
            },
            "hover": {
              "backgroundColor": "#f6f6f9",
              "color": ""
            },
            "selected": {
              "backgroundColor": "#e9ecef",
              "color": ""
            }
          },
          "list": {
            "backgroundColor": "#ffffff",
            "borderRadius": "4px",
            "boxShadow": "0 0 4px 0 rgba(110, 119, 125, 0.16)",
            "border": "solid 2px #e9ecef"
          }
        },
        "submit": {
          "base": {
            "backgroundColor": "",
            "color": "",
            "fontWeight": "",
            "fontSize": "",
            "borderRadius": "",
            "fontFamily": "",
            "border": "",
            "boxShadow": "",
            "width": "",
            "height": "",
            "padding": "",
            "cursor": ""
          },
          "hover": {
            "backgroundColor": "",
            "color": "",
            "fontWeight": "",
            "borderRadius": "",
            "border": "",
            "boxShadow": "",
            "transition": "0.3s"
          },
          "active": {
            "color": "",
            "backgroundColor": ""
          }
        },
        "clear": {
          "base": {
            "width": "24px",
            "height": "24px",
            "padding": "10px",
            "borderRadius": "50%",
            "backgroundColor": "transparent",
            "cursor": "pointer"
          },
          "hover": {
            "backgroundColor": "#e9ecef",
            "transition": "0.3s"
          },
          "active": {
            "backgroundColor": "#d7dbdf"
          }
        },
        "tooltip": {
          "button": {
            "base": {
              "width": "16px",
              "height": "16px",
              "border": "solid 1px #6e777d",
              "borderRadius": "50%",
              "backgroundColor": "#ffffff"
            },
            "hover": {
              "backgroundColor": "#e9ecef",
              "border": "",
              "borderRadius": "",
              "transition": "0.3s"
            },
            "active": {
              "backgroundColor": "#e9ecef",
              "border": "",
              "borderRadius": ""
            }
          },
          "content": {
            "base": {
              "padding": "16px 18px",
              "borderRadius": "4px",
              "boxShadow": "0 0 6px 0 rgba(0, 0, 0, 0.12)",
              "border": "solid 1px #ededed",
              "backgroundColor": "#ffffff"
            },
            "hover": {
              "padding": "",
              "borderRadius": "",
              "boxShadow": "",
              "border": "",
              "backgroundColor": "",
              "transition": "3000ms"
            }
          }
        },
        "cart": {
          "background": "none",
          "border": "none",
          "fontFamily": "inherit",
          "description": {
            "fontSize": "1.2rem",
            "fontWeight": 400,
            "color": "#1a1a1a"
          },
          "amount": {
            "fontSize": "1.4rem",
            "fontWeight": 600,
            "color": "#1a1a1a"
          },
          "quantityTitle": {
            "fontSize": "1.2rem",
            "color": "#6e777d"
          },
          "quantityValue": {
            "fontSize": "1.4rem",
            "fontWeight": 600,
            "color": "#4a4a4a"
          },
          "image": {
              "width": "",
              "height": "80px",
              "border": "none",
              "borderRadius": 0,
              "hover": {
                "border": "none",
                "borderRadius": 0,
                "transition": "0.3s"
              },
                "focus": {
                  "outline": "none"
              }
            }
          }, 
          "instructions": {
             "title": {
               "color": ""
             },
             "text": {
               "color": ""
             },
             "numbering": {
               "background": "",
               "text": ""
             }
          }  
        };
      ```

### Pass a Style Object

You can pass a style object in the init method, together with the rest of the fields. See example below:

- - JavaScript

    - ```javascript
      let checkout = new RapydCheckoutToolkit({
          pay_button_text: "Click to pay",
                // Text that appears on the 'Pay' button.
                // String. Maximum length is 16 characters.
                // Default is "Place Your Order". Optional.
                // If the client will pass a backgroundColor in the style object
          pay_button_color: "blue",
                // Color of the 'Pay' button. String.
                // Standard CSS color name or hexadecimal code such as #323fff.
                // Default is the color that is returned in the 'merchant_color'
                // field of the response to 'Create Checkout Page'. Optional.
          id: "checkout_9ebe58dcb9d75e8f972a35350f96c2fa",
                // ID of the 'Create Checkout Page' response. String. Required.
          close_on_complete: true,
                // Causes the embedded Rapyd Checkout Toolkit window to close
                // when the payment is complete. Boolean. Default is 'true'. Optional.    
          style: {
                global: {
                  fonts: [
                      "https://fonts.googleapis.com/css2?family=Mulish:wght@200&amp;display=swap",
                       {
                          family: 'myCustomFont',
                          src: '/fonts/myCustomFontRegular.woff2',
                          fontWeight: 400
                       },
                       {
                          family: 'myCustomFont',
                          src: '/fonts/myCustomFontBold.woff2',
                          fontWeight: 700
                       }
                  ]
              },
              submit: {
                  base: {
                      backgroundColor: '#0000FF',
                          // If passed for the 'submit' element, it will override the pay_button_color field.
                      fontFamily: 'myCustomFont',
         
                  }
              }  
      });
      ```