SDK Integration

Supported currencies: AUD & USD.
The JavaScript SDK allows you to securely accept card payments in your checkout flow with a few lines of code. This guide covers setup, initialization, payment creation, callback handling.

🔧 Environments

Environment	Script URL
Sandbox	`https://cdn.lightningpay.me/media/getkollo-sdk/1.1.0/sandbox/getkollo.js`
Production	`https://cdn.lightningpay.me/media/getkollo-sdk/1.1.0/prod/getkollo.js`

👉 View Demo Website

✅ Integration Steps

Step 1: Register Your App ID & Domain

Contact the Hello Clever team to register your domain and receive your app_id.

Step 2: Include SDK Script in Checkout Page

<script
  src="https://cdn.lightningpay.me/media/getkollo-sdk/1.1.0/sandbox/getkollo.js"
  async
></script>

Step 3: Add Mount Element in HTML

<div class="get-kollo"></div>

This is where the payment iframe will be injected. It must exist before calling createPayment().

Step 4: Initialize SDK and Create Payment

async function createGetKollo() {
  const getKolloSDK = new GetKollo({
    app_id: "your-app-id",
  });

  const init = await getKolloSDK.initialize();
  if (!init?.success) return alert(init?.error);

  const order = {
    external_id: "order-001",
    customer_name: "John Doe",
    customer_email: "john_doe@gmail.com",
    amount: 1000,
    currency: "USD",
    return_url: "https://yourdomain.com/success"
  };

  const options = {
    mountElement: ".get-kollo",
    styleProps: {
      frame: {
        width: "100%",
        height: "100%"
      }
    }
  };

  const resp = await getKolloSDK.createPayment(order, options);
  if (!resp?.success) return alert(resp?.error);

  window.getkolloCardCallback = (message) => {
    if (message?.status !== "succeeded") {
      alert(message?.error);
    }
  };
}

🧾 SDK Configuration Reference

`GetKollo({ app_id })`

app_id: Your unique application identifier (required)

const getKolloSDK = new GetKollo({
  app_id: [YOUR_APP_ID],
});

const init = await getKolloSDK.initialize();

`createPayment(order, options)`

🧾 `order` (required)

Field	Type	Required	Description
`external_id`	string	✅	Unique identifier for the order
`customer_name`	string	❌	Name of the customer
`customer_email`	string	❌	Email of the customer
`amount`	number	✅	Transaction amount in cents
`currency`	string	✅	`"USD"` or `"AUD"`
`return_url`	string	❌	URL to redirect after success/failure

⚙️ `options` (required)

Field	Type	Required	Description
`mountElement`	string	✅	CSS selector for mounting the iframe
`styleProps.frame.width`	string	❌	Width of iframe (default: `500px`)
`styleProps.frame.height`	string	❌	Height of iframe (default: `500px`)
`paymentButton`	enum	❌	Default: `'iframe'`. - `'iframe'`: use default payment button inside the iframe. - `'external'`: allows you to use your own custom button outside the iframe. In this case, you must trigger the payment by calling `getKolloSDK.onSubmit()` function when the button is clicked.
`events`	object	❌	Event handlers: - `onReady()`: Triggered when the payment form is fully loaded and ready for user input. - `onLoading(boolean)`: Used to manage the loading state of your external button.

const order = {
  external_id: [EXTERNAL_ID],
  customer_name: [CUSTOMER_NAME],
  customer_email: [CUSTOMER_EMAIL],
  amount: [ORDER_AMOUNT],
  currency: [CURRENCY], // USD or AUD
  return_url: [RETURN_URL], // optional redirect URL
};

const options = {
  mountElement: ".get-kollo", // Element classname or ID
  styleProps: {
    frame: {
      width: "100%",
      height: "100%",
    },
  },
  paymentButton: "iframe",
  // Event handlers
  events: {
    // Triggered when the payment form is fully loaded and ready for user input.
    onReady: () => {
      console.log("✅ Event: Payframe is ready.");
    },
    // paymentButton: 'external' - Used to manage the loading state of your external button.
    onLoading: (isLoading: boolean) => {
      console.log(`🔄 Event: Payframe loading state: ${isLoading}`);
    },
  }
};

const resp = await getKolloSDK.createPayment(order, options);

`onSubmit(payload)`

Use this to handle form submission when paymentButton is set to external.

🧾 `payload` (required)

Field	Type	Required	Description
`country`	string	✅	Two-letter country code (ISO 3166-1 alpha-2).
`postalCode`	string	❌	Required if the country is `US`, `GB`, or `CA`.

Example 1 – With required `postalCode` (US, GB, CA)

const payload = {
  country: "GB",
  postalCode: "SW1A 1AA"  // Required for US, GB, CA
}

getKolloSDK.onSubmit(payload)

Example 2 – Without `postalCode` (other countries)

const payload = { country: "VN" } // postalCode not required

getKolloSDK.onSubmit(payload)

Listener Payment status

After the payment is submitted, or if the card form fails to render, the SDK will trigger:

window.getkolloCardCallback = (response) => {
  if (response?.status !== "succeeded") {
    // If the card form fails to render in 7s, the SDK provides an error code.
    if (response?.error?.code === 'card_init_timeout') {
      // Handle rendering timeout.
    } else {
      alert(response?.error?.message);
    }
  }
};

Response Fields

Field	Description
`status`	`"succeeded"` or `"failed"`
`error`	An error object (message, code). Ex: The `"card_init_timeout"` code indicates the card form failed to render.
`order`	Order object as provided in the SDK call
`type`	`"callback"`

🔄 Reusing tokens for future payments

Call the Create Payment via Tokenisation API using your saved token. (token.id and token.type).

Note:

All payments created with tokens are processed as regular payments by default.
The unscheduled payment type is not supported for SDK integration.

Request Example

{
  "amount": 100,
  "currency": "AUD",
  "token": {
    "id": "tok_dfe1988a1ffc0d6562d3",
    "type": "card"
  },
  "external_id": "order_test_xxx",
  "return_url": "https://example.com",
  "capture": false,
  "webhook_notification": {
    "endpoint_url": "https://merchant.com/webhook",
    "authorization_header": "Bearer xxxxxx"
  }
}

Response Example

{
  "uuid": "7PPPMXIGH",
  "name": "Testing",
  "email": "test@example.com",
  "external_id": "wc_order_6C1hcvg4T7Pom",
  "status": "pending",
  "pay_code": {
    "3ds_url": "https://3ds-auth.example.com/verify"
  },
  "currency": "AUD",
  "amount": 100,
  "total": 100,
  "paid_amount": 0,
  "is_refundable": true,
  "payment_method": "card",
  "expired_at": "",
  "webhook_notification": {
    "endpoint_url": "https://webhook.site/456adb8f-4407-4bce-90fe-2c431db19696",
    "authorization_header": "****"
  },
  "refund_information": null,
  "sender_details": {
    "card": {
      "card_type": "card",
      "card_brand": "visa",
      "card_last_4": "1111",
      "card_country": "US"
    }
  },
  "capture": false,
  "payment_type": "regular",
  "token": {
    "id": "tok_dfe1988a1ffc0d6562d3",
    "type": "card"
  },
  "created_at": "2025-05-28T04:22:21.567+0000"
}

🔔 Webhook Notifications

When the payment status changes (e.g., pending → authorised → received),
Hello Clever will send a webhook event to your configured endpoint.

Token in webhook notifications:

When the payment reaches the authorised or waiting status, a token object is included in the webhook notification.

Token object example:

{
  "token": {
    "id": "tok_dfe1988a1ffc0d6562d3",
    "type": "card"
  }
}

Important: Save the token.id securely in your database. This token can be reused for future payments without requiring customers to re-enter their card details.

See the Webhook Documentation for:

Webhook object structure
Token inclusion after authorisation
Setting up webhooks and webhook security

📊 Payment Statuses

Status	Meaning
`pending`	Customer started a new payment but hasn't proceeded yet
`authorised`	Payment has been authorised, ready to be captured
`waiting`	Payment has been approved, awaiting funds to settle
`received`	Funds have been received
`expired`	Payment session expired before completion
`return_pending`	Refund request initiated, awaiting processing
`partially_refunded`	Partial refund has been issued to the customer
`return_received`	Full amount has been refunded to the customer
`return_expired`	Refund expired (after 10 days)
`return_rejected`	Refund request was denied
`failed`	Payment failed due to an error or decline
`in_dispute`	Customer has raised a dispute, under review
`dispute_lost`	Dispute has been resolved in customer's favour

🔧 Environments​

✅ Integration Steps​

Step 1: Register Your App ID & Domain​

Step 2: Include SDK Script in Checkout Page​

Step 3: Add Mount Element in HTML​

Step 4: Initialize SDK and Create Payment​

🧾 SDK Configuration Reference​

GetKollo({ app_id })​

createPayment(order, options)​

🧾 order (required)​

⚙️ options (required)​

onSubmit(payload)​

🧾 payload (required)​

Example 1 – With required postalCode (US, GB, CA)​

Example 2 – Without postalCode (other countries)​

Listener Payment status​

🔄 Reusing tokens for future payments​

🔔 Webhook Notifications​

📊 Payment Statuses​