STRABL Checkout SDK

The STRABL Checkout SDK is designed to help merchants integrate a seamless checkout experience with minimal configuration. It supports initializing STRABL configuration, environment switching, starting checkout and event handling for both successful and failed checkout.

The SDK is optimized for modern web applications, built with TypeScript for strong type safety. It is compatible with popular frameworks such as React, Next JS, Astro, Vue JS, Angular, and Laravel. It is lightweight, configurable, and designed to support both sandbox and production environments, making it suitable for both development and live deployments.

Supported Frameworks:

The STRABL Checkout SDK is framework-agnostic and designed to integrate easily with a wide range of modern front-end technologies. It supports both module-based and script-based usage.

• React
• Next.js
• Vue.js
• Angular
• Astro
• Laravel
• Plain JavaScript (ES6+)

Installation:

The STRABL Checkout SDK can be installed and integrated using multiple methods depending on the project setup and preferred package manager.

Using NPM:

  npm install @strabl-engineering/checkout-sdk

Using Yarn:

  yarn add @strabl-engineering/checkout-sdk

Using CDN Script:

Using jsDelivr CDN:

  <script src="https://cdn.jsdelivr.net/npm/@strabl-engineering/checkout-sdk@latest/dist/index.global.js"></script>

Using unpkg CDN:

  <script src="https://unpkg.com/@strabl-engineering/checkout-sdk@latest/dist/index.global.js"></script>

Available Methods:

The following functions/methods are available in the STRABL Checkout SDK:

1. initialize - to initialize the STRABL configuration

2. checkoutWithRedirect - to start the STRABL checkout with a full-page redirect

3. checkoutWithDialog - to start the STRABL checkout with a modal dialog

4. closeCheckoutDialog - to close the checkout dialog

1. Initialize:

The initialize method is an entry point for setting up the STRABL Checkout. It configures the SDK based on the merchant's platform configuration and desired environment.

This setup must be done before calling any other methods, like starting a checkout.

Parameters:

| Property | Type | Required | Description | |-----------------|----------------|--------------|---------------------------------------------------------------------------------| | platformUUID | String | Yes | Unique identifier for the merchant's platform. | | environment | String | No | Environment to use, either "sandbox" or "production". Defaults to "production". | | storeName | String | Yes | Name of the merchant's store for branding | | storeUrl | String | Yes | URL of the merchant's store for redirection after checkout. | | storeLogo | String | No | URL of the merchant's store logo for branding. Defaults to a default logo. | | buttonSelector | String | No | HTML selector for the checkout button. If provided, the SDK will replace the buttons with a STRABL designed button. If not provided, the SDK will not modify any buttons. Note: It will only modify UI of the button, it will not replace the onClick event. |

Usage:

  import StrablCheckout from '@strabl-engineering/checkout-sdk';

  StrablCheckout.initialize({
    platformUUID: 'merchant-abc-123',
    environment: StrablCheckout.ENVIRONMENT.SANDBOX, // optional
    storeName: 'My Store',
    storeUrl: 'https://mystore.com',
    storeLogo: 'https://mystore.com/logo.png' // optional
    buttonSelector: '#checkout-button' // optional
  });

2. Checkout with Redirect:

The checkoutWithRedirect method is used to start the STRABL checkout process with a full-page redirect. This method will perform a full-page redirect to STRABL’s hosted checkout page, where the user can complete their checkout. Once the checkout is finished, the user will be redirected back to your store.

Parameters:

| Property | Type | Required | Description | |--------------------|----------------|--------------|---------------------------------------------------------------------------------| | cart | Cart | Yes | This is the cart object that contains all the line_items, currency, extra order meta. For more details, refer to the Cart interface | | isExpressCheckout | Boolean | No | If true, checkout will provide an option to add more products to the cart. |

Usage:

  import StrablCheckout from '@strabl-engineering/checkout-sdk';

  StrablCheckout.checkoutWithRedirect({
    cart: {
      currency: "AED",
      lineItems: [
        new StrablCheckout.Product({
          price: 100,
          quantity: 1,
          productId: "12345678",
          title: "Test Product",
          description: "This is a test product",
          variantId: "variant-12345678",
          image:
            "https://example.com/product-image.jpg",
          variantOptions: {
            size: "Large",
            color: "Black",
          },
        }),
      ],
    },
    isExpressCheckout: false,
  });

3. Checkout with Dialog:

The checkoutWithRedirect method is used to start the STRABL checkout process with modal dialog. This method will open an in-place checkout interface using an iframe modal, allowing users to complete checkout without leaving your website.

Parameters:

| Property | Type | Required | Description | |--------------------|----------------------|--------------|-------------------------------------------------------------------------------------| | cart | Cart | Yes | This is the cart object that contains all the line_items, currency, extra order meta. For more details, refer to the Cart interface | | isExpressCheckout | Boolean | No | If true, checkout will provide an option to add more products to the cart. | | onSuccess | CallBack function | No | Function that will be called after a successful checkout. | | onFailure | CallBack function | No | Function that will be called if the payment fails during checkout. |

Usage:

  import StrablCheckout from '@strabl-engineering/checkout-sdk';


  StrablCheckout.checkoutWithDialog({
    cart: {
      currency: "AED",
      lineItems: [
        new StrablCheckout.Product({
          price: 100,
          quantity: 1,
          productId: "12345678",
          title: "Test Product",
          description: "This is a test product",
          variantId: "variant-12345678",
          image:
            "https://example.com/product-image.jpg",
          variantOptions: {
            size: "Large",
            color: "Black",
          },
        }),
      ],
    },
    isExpressCheckout: false,
    onSuccess: (data) => {
      console.log("Checkout Success:", data);
    },
    onFailure: (error) => {
      console.error("Checkout Failed:", error);
    },
  });

4. Close Checkout Dialog:

The closeCheckoutDialog method can be used to close STRABL checkout dialog. If you want to close dialog for any reason, you can call this function to close it.

Usage:

  import StrablCheckout from '@strabl-engineering/checkout-sdk';


  StrablCheckout.closeCheckoutDialog();

Interfaces

Product Interface:

The Product interface defines the structure of each line item passed to the cart object. This object represents an individual product that the customer is purchasing. All products in the cart must follow this schema.

Properties:

| Property | Type | Required | Description | |----------------|--------------------|--------------|---------------------------------------------------------------------------------| | title | String | Yes | The name/title of the product. | | description | String | No | A brief description of the product. | | price | Number | Yes | The price of the product (in the smallest currency unit). | | sku | String | Yes | Stock Keeping Unit identifier for inventory management. | | productId | String | Yes | Unique identifier for the product. | | variantId | String | Yes | Unique identifier for the specific product variant. | | url | String | No | An optional link to view the product on the website. | | image | String | No | URL of the product image. | | quantity | Number | Yes | The quantity of this product in the cart. | | variantOptions | string[] or Record<string,string> | No | List of variant options (e.g., Size: M, Color: Red). |

Sample:

// Product sample with variant options as array of strings
{
  price: 100,
  quantity: 1,
  productId: "12345678",
  title: "Test Product",
  description: "This is a test product",
  variantId: "variant-12345678",
  image:
    "https://example.com/product-image.jpg",
  variantOptions: [
    "size: Large",
    "color: Black",
  ]
}

// Product sample with variant options as Record of key value pair
{
  price: 100,
  quantity: 1,
  productId: "12345678",
  title: "Test Product",
  description: "This is a test product",
  variantId: "variant-12345678",
  image:
    "https://example.com/product-image.jpg",
  variantOptions: {
    size: "Large",
    color: "Black",
  },
}

Cart Interface:

The Cart interface defines the structure of cart data passed to the methods to start checkout session. This object represents whole cart data.

Properties:

| Property | Type | Required | Description | |----------------|--------------------------------------------------|----------|----------------------------------------------------------------------------------------| | currency | String | Yes | The currency ISO code (e.g., USD, PKR, EUR). | | country | String | No | Country of the customer or where the checkout is initiated (e.g., US, PK, DE). | | lineItems | Product[] | Yes | List of product objects included in the order (see Product definition). | | extra | Record<string, string \| number \| boolean> | No | Additional key-value pairs for metadata or tracking. | | merchantUrls | { successUrl?, failureUrl?, cancelUrl? } | No | An object containing redirect URLs for the post-checkout flow. If provided, the user will be redirected to these URLs after checkout events. |

Sample:

  const cart = {
    currency: "AED",
    lineItems: [
      {
        price: 100,
        quantity: 1,
        productId: "12345678",
        title: "Test Product",
        description: "This is a test product",
        variantId: "variant-12345678",
        image:
          "https://example.com/product-image.jpg",
        variantOptions: {
          size: "Large",
          color: "Black",
        },
      },
      {
        price: 100,
        quantity: 1,
        productId: "12345678",
        title: "Test Product 2",
        description: "This is a test product 2",
        variantId: "variant-12345678",
        image:
          "https://example.com/product-image.jpg",
        variantOptions: [
          "size: Large",
          "color: Black",
        ]
      }
    ],
    country: "AE",
    extra: {
      trackingId: "123456",
    },
    merchantUrls: {
      successUrl: "https://mystore.com/checkout/success",
      failureUrl: "https://mystore.com/checkout/failed",
      cancelUrl: "https://mystore.com/checkout/cancel",
    },
    isExpressCheckout: false,
  };

Merchant URLs:

The merchantUrls object defines the set of optional URLs used to redirect the customer after the checkout process completes. These URLs allow the merchant to control where the customer is taken based on the checkout result, whether it is successful, failed, or canceled.

Properties:

| Property | Type | Required | Description | |----------------|--------------------------|----------|----------------------------------------------------------------------------------| | successUrl | String | Yes | The URL to redirect the user to after a successful checkout. | | failureUrl | String | No | The URL to redirect the user to after a if payment fails during the checkout. | | cancelUrl | String | Yes | The URL to redirect the user cancel checkout. |

Sample:

  {
    successUrl: "https://abc.com/cart/success",
    failureUrl: "https://abc.com/cart/failed",
    cancelUrl: "https://abc.com/cart/canceled",
  }

Cart and Product Classes

To provide a cleaner and more structured integration experience, the STRABL Checkout SDK includes two utility classes: Product and Cart.

These classes enable developers to easily build valid cart objects using a class-based approach, rather than manually creating nested objects. This pattern improves readability, enforces schema consistency, and type safety. Developers can use the Product class to create individual product instances and then use the Cart class to group those products into a cart object. The resulting cart can be passed directly to the createCheckoutSession method.

Usage:

  import StrablCheckout from '@strabl-engineering/checkout-sdk';

  const product1 = new StrablCheckout.Product({
      title: "Test Product",
      description: "This is a test product",
      price: 100,
      quantity: 1,
      productId: "12345678",
      variantId: "variant-12345678",
      image:
        "https://example.com/product-image.jpg",
      variantOptions: {
        size: "Large",
        color: "Black",
      },
  });

  const cart = new StrablCheckout.Cart({
    currency: "AED",
    lineItems: [product1],
    extra: {
      trackingId: "123456"
    },
  })