Strabl PAY SDK

STRABL Pay SDK is the fastest way to embed secure, lightweight & PCI-DSS compliant card payments inside any website — providing a unified interface across modern web frameworks while keeping the payment experience smooth and seamless

For developers — Lightweight, framework-agnostic, and PCI-DSS compliant out of the box. Integrate in minutes, not days

For UI/UX designers — Every element is fully customizable. Match your checkout to your brand without any friction

For merchants & businesses — A unified, reliable payment experience that builds customer trust from the first transaction

Supported Frameworks:

The STRABL Pay 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 STRABL Pay SDK can be installed and integrated using multiple methods depending on the project setup and preferred package manager.

Using NPM:

  npm install @strabl-engineering/strabl-pay

Using Yarn:

  yarn add @strabl-engineering/strabl-pay

Using CDN Script:

Using jsDelivr CDN:

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

Using unpkg CDN:

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

Supported Parameters

| Parameter | Type | Required | Description | | :--- | :--- | :--- | :--- | | platformUuid | string | Yes | Your unique platform identifier. | | apiKey | string | Yes | Your public API key for authentication. You can create it from STRABL merchant dashboard | | currencyCode | string | Yes | 3-letter ISO currency code (e.g., "AED", "SAR", "USD"). | | amount | number | Yes | The total transaction amount to be charged. (e.g., 100). | | language | "en" | "ar" | Yes | Sets the display language. | | paymentMethods | PaymentMethod[] | No | Array of allowed payment methods which will be shown to the cusotmer (e.g., ["card", "applepay"]). | | fieldInputStyle | "floating-label" | "outlined" | No | Defines the visual style of the form input fields. | | customstyles | object | No | Object containing the different properties to customize the UI. Full custom styles object is attached below | | customer | object | No | Optional object containing customer name and email. | | onPaymentSubmission | () => Promise<boolean> | No | Callback triggered before submission; return true to proceed. You can add your required validations here. If retruned false, it will not proceed to the payment submission.| | onPaymentSuccess | (orderShortCode: string) => void | No | Callback triggered after a successful transaction. It will return STRABL order short code which you can store. | | onPaymentFailed | (failureReason: string) => void | No | Callback triggered when a payment fails or is declined. It will return failure reason.|

Customization Styles (customstyles)

You can pass the following properties within the customstyles object to match your brand's identity:

| Parameter | Type | Description | | :--- | :--- | :--- | | textColor | string | Sets the color for labels and standard text. | | errorColor | string | Sets the color for validation and transaction error messages. | | accentColor | string | Sets the primary color for buttons and active states. | | backgroundColor | string | Sets the background color of the form container. | | btnRadius | string | Sets the border-radius for the submit button (e.g., "4px"). | | btnPadding | string | Sets the internal padding for the submit button. | | inputRadius | string | Sets the border-radius for the input fields. | | inputBorderColor | string | Sets the color of the input field borders. | | inputBorderWidth | string | Sets the thickness of the input borders (e.g., "1px"). | | continerMaxWidth | string | Limits the maximum width of the form container. | | fontFamily | string | Sets the font stack for the entire component. |

In order to submit the payment, publish a custom strabl-submit-card-form event from your JavaScript code. The SDK will listen for this event and trigger the payment process.

window.dispatchEvent(new CustomEvent("strabl-submit-card-form"));

Events and Callbacks

The component provides two ways to handle transaction outcomes: Callbacks (props/properties) and Standard DOM Events. While both serve the same purpose, DOM events are particularly useful in Vanilla JS and Angular for decoupling logic.

1. Payment Success

Triggered when the transaction is successfully authorized and completed.

• Callback (onPaymentSuccess): A function property that receives the orderShortCode as a string.
• DOM Event (strablPaymentSuccess): A standard event dispatched by the component. The orderShortCode is accessible via event.detail.

// Example using Event Listener
paymentForm.addEventListener("strablPaymentSuccess", (event) => {
  console.log("Order Code:", event.detail);
});

2. Payment Failed

Triggered when the payment is declined, cancelled, or encounters a processing error.

• Callback (onPaymentFailed): A function property that receives a failureReason string (e.g., "Insufficient funds" or "Invalid CVV").
• DOM Event (strablPaymentFailed): A standard event dispatched by the component. The failure reason is accessible via event.detail.

// Example using Event Listener
paymentForm.addEventListener("strablPaymentFailed", (event) => {
  console.error("Failure Reason:", event.detail);
});

Usage

1. React

import { StrablCardPaymentForm } from "@strabl-engineering/strabl-pay/react";

export function Checkout() {
  return (
    <StrablCardPaymentForm
      platformUuid="YOUR_PLATFORM_UUID"
      apiKey="YOUR_PUBLIC_API_KEY"
      amount={100}
      language="en" // "en" or "ar"
      currencyCode='AED'
      paymentMethods={["card", "applepay"]}
      onPaymentSubmission={async () => {
        console.log("Submit Payment clicked");
        // Perform any necessary validation or actions before submitting the payment form.
        // Return true to proceed with the payment submission, or false to prevent it.
        return true;
      }}
      fieldInputStyle='floating-label' // outlined or floating-label
      onPaymentSuccess={(strablOrderShortCode) => {
        // Handle post-payment success actions, such as displaying a confirmation message or redirecting the user.
        console.log("Payment successful! Strabl Order short code:", strablOrderShortCode);
      }}
      onPaymentFailed={(failureReason) => {
        // Handle post-payment failure actions, such as displaying a error message.
        console.log("Payment Failed! reason:", failureReason);
      }}
      customer={{
        email: "",
        name: ""
      }}
      customstyles={{
        textColor: "#3a3a3a",
        accentColor: "#000000cc",
        backgroundColor: "#ffffff",
        btnPadding: "10px 16px",
        btnRadius: "4px",
        continerMaxWidth: "500px",
        fontFamily: "'GT-America', sans-serif",
        errorColor: "#ff485c",
        inputBorderColor: "#0000003b",
        inputBorderWidth: "1px",
        inputRadius: "4px",
      }}
    />
  );
}

If you are using TypeScript, you can import the types for better type safety in your vite-env.d.ts or any declaration file:

/// <reference types="vite/client" />
import { StrablCardFormProps } from "@strabl-engineering/strabl-pay/react";

declare module "react" {
  namespace JSX {
    interface IntrinsicElements {
      StrablCardPaymentForm: StrablCardFormProps;
    }
  }
}

2. Angular

In your AppModule (for NgModule-based apps) or in your Component (for Standalone apps), add the CUSTOM_ELEMENTS_SCHEMA.

import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import '@strabl-engineering/strabl-pay'; // Import the web component loader

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule],
  providers: [],
  bootstrap: [AppComponent],
  schemas: [CUSTOM_ELEMENTS_SCHEMA] // Allows using 'strabl-card-payment-form'
})
export class AppModule { }

Step 2: Component Logic

Define your configuration and handlers in your TypeScript file.

import { Component } from '@angular/core';

@Component({
  selector: 'app-checkout',
  templateUrl: './checkout.component.html'
})
export class CheckoutComponent {
  config = {
    platformUuid: "YOUR_PLATFORM_UUID",
    apiKey: "YOUR_PUBLIC_API_KEY",
    amount: 100,
    currencyCode: 'AED',
    language: 'en',
    paymentMethods: ["card", "applepay"],
    fieldInputStyle: 'floating-label',
    customer: { email: "", name: "" },
    styles: {
      textColor: "#3a3a3a",
      accentColor: "#000000cc",
      backgroundColor: "#ffffff",
      btnPadding: "10px 16px",
      btnRadius: "4px",
      continerMaxWidth: "500px",
      fontFamily: "'GT-America', sans-serif",
      errorColor: "#ff485c",
      inputBorderColor: "#0000003b",
      inputBorderWidth: "1px",
      inputRadius: "4px",
    }
  };

  async handleSubmission() {
    console.log("Submit Payment clicked");
    return true; // Return true to proceed
  }

  onSuccess(event: any) {
    // Web components dispatch custom events, details are in event.detail
    console.log("Payment successful!", event.detail);
  }

  onFailed(event: any) {
    console.log("Payment Failed!", event.detail);
  }
}

Step 3: Template Usage

Use property binding [] for inputs and event binding () for outputs. Note that Web Components often use standard kebab-case or the specific event names defined in the library.

<strabl-card-payment-form
  [platformUuid]="config.platformUuid"
  [apiKey]="config.apiKey"
  [amount]="config.amount"
  [currencyCode]="config.currencyCode"
  [language]="config.language"
  [paymentMethods]="config.paymentMethods"
  [fieldInputStyle]="config.fieldInputStyle"
  [customer]="config.customer"
  [customstyles]="config.styles"
  (strablPaymentSuccess)="onSuccess($event)"
  (strablPaymentFailed)="onFailed($event)">
</strabl-card-payment-form>

3. Plain HTML / JavaScript

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Strabl Checkout</title>
  <!-- Load the SDK -->
  <script type="module" src="https://unpkg.com/@strabl-engineering/strabl-pay@latest/dist/index.js"></script>
</head>
<body>

  <!-- Use the custom tag directly -->
  <strabl-card-payment-form id="strabl-form"></strabl-card-payment-form>

  <script type="module">
    const form = document.getElementById('strabl-form');

    // Set properties
    form.platformUuid = "YOUR_PLATFORM_UUID";
    form.apiKey = "YOUR_PUBLIC_API_KEY";
    form.amount = 100;
    form.currencyCode = "AED";
    form.language = "en";
    form.paymentMethods = ["card", "applepay"];
    form.fieldInputStyle = "floating-label";
    
    form.customstyles = {
      textColor: "#3a3a3a",
      accentColor: "#000000cc",
      backgroundColor: "#ffffff",
      btnPadding: "10px 16px",
      btnRadius: "4px",
      continerMaxWidth: "500px",
      fontFamily: "'GT-America', sans-serif",
      errorColor: "#ff485c",
      inputBorderColor: "#0000003b",
      inputBorderWidth: "1px",
      inputRadius: "4px",
    };

    // Listen for events
    form.addEventListener('strablPaymentSuccess', (event) => {
      console.log("Success! Order Code:", event.detail);
    });

    form.addEventListener('strablPaymentFailed', (event) => {
      console.error("Failed! Reason:", event.detail);
    });
  </script>
</body>
</html>

In order to submit the payment, publish a custom strabl-submit-card-form event from your JavaScript code. The SDK will listen for this event and trigger the payment process.

window.dispatchEvent(new CustomEvent("strabl-submit-card-form"));