Embedding Checkout

You can embed our checkout experience on your website easily by using our integration script.

Embedding Options

The embedding scripts support multiple operations as explained below. Depending on the operation, there are different numbers of arguments, and each argument's position might have a different meaning. All configurations always start with the operation name as the first argument (i.e., sb({operationName}, ...{args})).

Initializing the Site Id

(Required)
To initialize the embedding script, you must specify the "Site Id". This is accomplished using the siteId operation as demonstrated below:

sb("siteId", "{your_siteId})");

Where:

{your_siteId} refers to the case-sensitive site id you want to use, which contains the plans you need to attach. Your Subsbase Admin Portal link follows this format: https://{siteId}.subsbase.io

This operation should exist only once, adding it more than once can lead to unexpected behavior.

Customizing Theme

(Optional)

Primary Color

You have the option to customize the primary color used in various parts of the checkout experience.
This can be achieved using the theme operation as demonstrated below:

sb("theme", "{theme})");

Where:

{theme} represents the primary color you want to use in hex format (i.e #FFFFFF)

This is an optional operation, if you do not specify a theme, the default value is #20407D.

This operation should exist only once, adding it more than once can lead to unexpected behavior.

Payment Button Text

To allow the customization of the payment button text, use the payBtnText query parameter.
If you want to set the payment button text to "Pay", you would use:

sb("queryParam", "payBtnText", "Pay");

The payment button text also supports Arabic. You can set it using:

sb("queryParam", "payBtnText", "ادفع الآن");

The "Payment Button Text" feature is currently supported only in Checkout.com. Other payment providers are expected to support this feature in future releases.

Autosize Option

(Optional)

The autosize option controls the height of the embedded checkout container.
There are two options for the autosize option:
- true: If you set the autosize option to true, the embedding script will dynamically adjust the height of the container to fit the content. This is recommended if you don't want to set any heights on the container element yourself.
- false: If you set the autosize option to false, the height of the container will be determined by the height that you set on the container element.

Here is an example of how to use the autosize option:

sb('config', 'autosize', true);

This code will set the autosize option to true, and the embedding script will dynamically adjust the height of the container.
It is recommended that you use the autosize option with the true value to ensure that the checkout form is always displayed correctly.

Adding a Callback

(Optional)

Callbacks allow you to trigger specific actions during different stages of the checkout process. These actions can communicate with your backend, handle redirections, log information, or any custom operation you define.
You can set up callbacks using the sb function with the callback operation. The function receives an event object (e) containing all relevant signup details, such as InfoFields, CustomFields, PlanCustomization, and more.

Here’s the syntax for adding a callback:

sb("callback[event]", (e) => { /* custom action */ });

Where:

event refers to the specific event in the checkout process (e.g., info fields completion, payment method selection, etc.).
e is the event object containing details related to that event or stage in the process.

Available Callback Events

Info Fields Filled
Triggered after the user fills in all required info fields.
```
sb("callback[infofieldsFilled]", (e) => console.log("InfoFields result:", { e }));  
```
Customization Confirmed
Triggered after the user confirms their plan customization details.
```
sb("callback[customizationConfirmed]", (e) => console.log("Customization result:", { e }));  
```

Payment Method Selected
Triggered when the user selects a payment method.

sb("callback[paymentMethodSelected]", (e) => console.log("PaymentMethod result:", { e }));

Payment Success
Triggered after a successful payment transaction, indicating the user has completed the payment process successfully.
```
sb("callback[success]", (e) => console.log("Success result:", { e }));  
```

This operation should exist only once, adding it more than once can lead to unexpected behavior.

Checkout Version

(Optional)
You have the option to specify the checkout version you want to use. By including the following code, you can choose to use Checkout Version 2 :

sb("checkoutVersion", "v2");

Ensure that you specify "v2" to use Checkout Version 2.

Version Specification

The "checkoutVersion" parameter only accepts the value "v2." If you provide any other value, it will not be recognized, and the default version (Version 1) will be used.

If you do not specify a version, the system will default to Version 1.

Plan Checkout

There are two ways to integrate the checkout experience: (At least one is needed, unless plan picker is used.)

1. Attaching the Subscription Plans to Clickable Elements on Your Page
2. Attaching the Subscription Plans Inline to Container Elements

You can do this by using the attachPlan or inlinePlan operations as follows:

1. Attaching the Subscription Plans to Clickable Elements

sb(
  "attachPlan",
  "{planCode}",
  "{clickableElementReference}",
  ["class|id"],
  ["{attachEvent}"]
);

Where:

{planCode} is the case-sensitive plan code that needs to be attached. You define the 'Plan Code' while creating it
{clickableElementReference} is either the value of the class name or id added to the clickable element on which you want to attach a plan. If the clickable element reference is a class and placed on multiple elements, all elements will open the same plan.
"class|id" should be either "class" or "id". If not specified, default value is "id"
"attachEvent" is a case-sensitive event name on which to trigger the checkout overlay. The event name has to be a valid HTML DOM Event, you can find more here and here If not specified, default value is "click"

This operation should exist at least once and should be repeated as many times as needed to attach all your plans to the required clickable elements.

Attaching Plan Using Element's ID

Example:
If you have the following element and want to attach it to a plan with the code pro-plan:

<button id="pro-plan-btn">Pro Plan</button>

Attach using the element's ID:

sb("attachPlan", "pro-plan", "pro-plan-btn", "id");

This code snippet links the "Pro Plan" button with the subscription plan identified by the code pro-plan.

Attaching Plan Using Element's Class Name

Example:
If you have the following element and want to attach it to a plan with the code pro-plan:

<button class="pro-plan-btn">Pro Plan</button>

Attach using the class name

sb("attachPlan", "pro-plan", "pro-plan-btn", "class");

This code snippet links the "Pro Plan" button with the subscription plan identified by the code pro-plan. It utilizes the class name pro-plan-btn to establish this connection.

2. Attaching the Subscription Plans Inline to Container Elements

In addition to the previous method of integrating the checkout experience, you can also inline the checkout experience in a page of your own by replacing the operation name attachPlan by inlinePlan to use the Inline Checkout Experience. This creates an iFrame element and injects it to the provided container element.

sb("inlinePlan", "{planCode}", "{containerElementReference}", ["class|id"]);

Where:

{containerElementReference} is the provided container element reference, a div as an example.
"class|id" should be either "class" or "id". If not specified, default value is "id"

You have to set the width and the height for the Container Element and the injected iFrame will fill the entire container i.e. the iframe's height and width are set to 100%.

Setting Redirection for Successful Checkout

(Optional)
Sometimes you need to have the checkout experience automatically redirect to your website after a successful checkout. You can do this by using the queryParam operation as follows:

sb("queryParam", "redirects[success]", "{url}");

Where:

"{url}" is a placeholder that stands for the full web address where users will be directed after a successful checkout. It is crucial to input the complete URL (example: https://www.example.com/landing-page) for the redirection to function accurately.
"redirects[success]" specifically denotes the condition for redirecting users when two criteria are met:
1. The card has been tokenized successfully.
2. The associated invoice status is marked as "Processing."

It is essential to note that this condition does not indicate a successful payment or the invoice being in the "Paid" status. Instead, it signifies the completion of the card tokenization process and the invoice being in the "Processing" phase.

This is an optional operation, and you can use it as many times as needed. Duplicated params might cause unexpected behavior.

Setting Redirection after Successful Payment

(Optional)

For successful payments, you may want users to be automatically redirected to your website. To enable this, use the queryParam operation as follows:

sb("queryParam", "redirects[invoicePaid]", "{url}");

Where:

"{url}" is a placeholder that stands for the full web address where users will be directed after a successful payment. It's crucial to input the complete URL (example: https://www.example.com/landing-page) for the redirection to function accurately.

This is an optional operation, and you can use it as many times as needed. Duplicated params might cause unexpected behavior.

Pre-filling Info Fields and Custom Fields

(Optional)
Sometimes you need to attach some custom fields to the checking out clients (visible in the Subsbase Admin Portal) or pre-fill any of the info fields in the checkout experience. You can do this by using the queryParam operation as follows:

sb("queryParam", "{param}", "{value}");

Where:

"{param}" is the parameter you wish to pre-fill/attach
"{value}" is the value you need to specify for that particular parameter

Allow Geolocation

If you require access to the user's geolocation information, include the allow="geolocation" attribute within the iframe element.

<html>
  <iframe
    allow="geolocation"
    src="https://subsbase.subscribe.test-site.xyz"
  >
  </iframe>
</html>

Where:

"allow" is the name of the attribute being set. The allow attribute specifies a set of restrictions to be applied to the content within the iframe.
"geolocation" is the value assigned to the allow attribute. In this context, it indicates that the iframe content is allowed to access the user's geolocation information.
- Combining these details, adding the allow="geolocation" attribute to the iframe element, enabling it to access the user's geolocation information if needed.

Pre-filling Info Fields

To pre-fill an info field the parameter should be infoFields[{fieldName}]. For example, to pre-fill the name field with the value John Doe you would use:

sb("queryParam", "infoFields[name]", "John Doe");

Please note that fieldName is case-sensitive and should match the field name you chose while creating the plan. This will work on any field you have configured on your plans.

Prevent the User from Editing Info Fields

You can make info fields uneditable by setting the disableInfoFields parameter value to true as shown below:

sb("queryParam", "disableInfoFields", true);

Default value is false

Pre-filling Custom Fields

To pre-fill an info field the parameter should be customFields[{fieldName}].

Specifying the Checkout Language

To pre-fill the preferred language for the checkout session, you can use the customFields[preferred-language] parameter. This allows you to specify whether the session should load in Arabic or English.

To set the preferred language to Arabic, use:

sb("queryParam", "customFields[preferred-language]", "ar");

To set the preferred language to English, use:

sb("queryParam", "customFields[preferred-language]", "en");

Including the User Agent Information

To attach a userAgent custom field with the value navigator.userAgent, use:

sb("queryParam", "customFields[userAgent]", navigator.userAgent);

This is an optional operation, and you can use it as many times as needed.
Duplicated params might cause unexpected behavior.

Beware, adding too many info fields and custom fields can result in long urls for loading your checkout experience, so keep that in mind while using this operation.

Setting Customer Identifiers

By default, a random identifier (customerId) is automtically generated while creating a new customer that signs up. In some cases, it is needed to pre-set the customer identifier (customerId) to match pre-existing info in your system or to follow a certain convention. In this case, you need to supply the desired customer for each customer as a pre-filled custom field as discussed above. The 'customerId` key is to be used as shown below:

sb('queryParam', "customFields[customerId]", {desired-customerId})

This has a side effect that the embedding script is dynamically set during navigation or a customerId is auto-generated while the script is rendered. You have make sure that correct value is supplied. Duplicate customerIds would cause a failure during sign up.

Putting It All Together

Put the below script before your website's closing head tag </head>.

HTML V1

<script>
(function (d, o, s, a, m) {
  a = d.createElement(o);
  m = d.getElementsByTagName(o)[0];
  a.async = 1;
  a.src = s;
  m.parentNode.insertBefore(a, m);
})(document, "script", "https://embed.subsbase.com/sb.min.js");
window.sb =
  window.sb ||
  function () {
    (sb.s = sb.s || []).push(arguments);
  };
sb("siteId", "{your_siteId}"); // Required.
sb("theme", "{hex-code}"); // Optional. Example: sb('theme', '#20407d')
sb("callback", (e) => console.log("signup result:", { e })); // Optional.
sb(
  "attachPlan",
  "{planCode}",
  "{clickableElementReference}",
  ["class|id"],
  ["{attachEvent}"]
); // At least one is required. Can be repeated.
sb("queryParam", "redirects[success]", "{url}"); // Optional,
sb("queryParam", "redirects[invoicePaid]", "{url}"); // Optional.
sb("queryParam", "{param}", "{value}"); // Optional. Can be repeated.
sb("queryParam", "disableInfoFields", true); // Optional.
</script>

Integration GuideGetting Started

Integration GuideEmbedding Plan Picker