Checkout Toolkit Integration

The most customized path for accepting more payment methods.

Create Your Own Customized Page with Checkout Toolkit

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.

Your mobile and desktop friendly shoppers are never redirected away from your website.

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, click here 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").

📘

As Rapyd Checkout Toolkit is always filtered for just one payment method type category, you need to specify one payment method type category in 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, use the following code:
<script src="https://sandboxcheckouttoolkit.rapyd.net"></script>
  1. Add a <div> tag with id="rapyd-checkout":
<div id="rapyd-checkout"></div>
  1. Initialize the Checkout Page object with the following fields:
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.
    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.
});
  1. Call display Checkout() to display the checkout page.
checkout.displayCheckout();
  1. Optional step. If close_on_complete is set to false, call checkout.closeCheckout() to close the Rapyd Checkout Toolkit window.
checkout.closeCheckout();
  1. Insert your code that runs when the following events occur. Use your code to read the event field in the window object.
window.addEventListener('onCheckoutPaymentSuccess', (event) => {
                    console.log(event.detail)
                    // Returns 'Payment' object.
                    // Client code.
})

window.addEventListener('onCheckoutFailure', (event) => {
                    console.error(event.detail.error)
                    // Returns an error message from the API.
                    // Client code.
})

window.addEventListener('onLoading', (event) => {
                    console.error(event.detail.error)
                    // returns true or false depending on the loading state
                    // client code
})

Sample Embedded Rapyd Checkout Toolkit

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

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('onCheckoutFailure', 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.

📘

See Payment Object for more details.

Take note of the following fields in the Payment Object and the tasks associated with each of them.

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.
NEW - Not closed.

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.

Checkout Toolkit Customizations

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

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:

  • English
  • Spanish
  • Icelandic
  • German
  • Korean
  • Portuguese
  • Simplified Chinese
  • Traditional Chinese
  • Thai
  • Japenese
  • Indonesian
  • Tagalog
  • Vietnamese
  • Bahasa Malayu (Malaysian)

Specify it in the language parameter field when generating the Checkout page.
Note: Additional languages coming soon!

Custom CSS

Elements

The table below lists all the available elements:

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.
global = {
  fonts: [
    "https://fonts.googleapis.com/css2?family=Mulish:[email protected]&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).

📘

  • 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
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"
      }
    }
  }
  };
Pass a Style object

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

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:[email protected]&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',
   
            }
        }  
});

Updated 4 days ago


What's Next

Complete Payment

Checkout Toolkit Integration


The most customized path for accepting more payment methods.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.