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",
    payment_type: "regular"
  };

  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
`payment_type`	enum	❌	The type of payment. One of `regular` \| `unscheduled`. Default: `regular`.

⚙️ `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
  payment_type: "regular", // optional: "regular" | "unscheduled"
};

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"`

💳 Payment Types

1️⃣ Regular Payment

Customers can request to store their card details during a payment, which you can then use for future payments without customers having to re-enter the details.

SCA requirements
In regions that require Strong Customer Authentication (SCA) — the customer must complete a 3D Secure (3DS) challenge during the payment process.
When SCA is required, the API response includes a pay_code.3ds_url field — redirect your customer to this URL to complete the authentication.

Set up a regular payment

Pass payment_type: "regular" in the order object when calling createPayment(). This is optional and defaults to "regular" if not provided.

Request Example

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",
  payment_type: "regular",
};

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

2️⃣ Unscheduled Payment

With an unscheduled payment agreement, you can request to store a customer's card details during an initial transaction and perform a card-not-present transaction with the stored card at a later date.

For example, a customer may provide their card details when checking in to a hotel, but will only be charged after they check out, at which point they may have incurred additional charges.

SCA requirements
Merchant-initiated transactions fall out of scope of SCA and qualify for exemption under Merchant Initiated Exclusion, meaning 3DS authentication is not required.

Set up an unscheduled payment

Initial payment (SDK): Pass payment_type: "unscheduled" in the order object when calling createPayment() to store the customer's card details.

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",
  payment_type: "unscheduled",
};

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

Subsequent payments (Tokenisation API): Use the saved token via Create Payment via Tokenisation with the following fields:

payment_type = "unscheduled"
previous_payment_uuid — the uuid returned from the initial payment's response. Including this references the original SCA-authorised transaction and improves approval rates.
charge_reason — recommended to improve approval rates and chargeback processes. One of:
- resubmission – Use when the original purchase has occurred, but you could not get authorization at the time that goods or services were provided.
- delayed_charge – Use when there is a delayed charge.
- no_show – Use when the cardholder entered into an agreement to purchase but they failed to meet the terms of the agreement.
- reauthorisation – Use when an additional purchase was made after the original purchase, typically for delayed or split orders.

Request Example

{
  "amount": 100,
  "currency": "AUD",
  "token": {
    "id": "tok_dfe1988a1ffc0d6562d3",
    "type": "card"
  },
  "external_id": "order_test_xxx",
  "return_url": "https://example.com",
  "capture": false,
  "payment_type": "unscheduled",
  "charge_reason": "delayed_charge",
  "previous_payment_uuid": "7PPPMXIGH",
  "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": "authorised",
  "currency": "AUD",
  "amount": 100,
  "total": 100,
  "paid_amount": 0,
  "is_refundable": true,
  "payment_method": "card",
  "capture": false,
  "payment_type": "unscheduled",
  "token": {
    "id": "tok_dfe1988a1ffc0d6562d3",
    "type": "card"
  },
  "created_at": "2025-05-28T04:22:21.567+0000"
}

🔄 Reusing tokens for future payments

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

For regular and unscheduled payment types, see the Payment Types section above.

Note:

payment_type defaults to regular if not provided.

Request Example

{
  "amount": 100,
  "currency": "AUD",
  "token": {
    "id": "tok_dfe1988a1ffc0d6562d3",
    "type": "card"
  },
  "external_id": "order_test_xxx",
  "return_url": "https://example.com",
  "capture": false,
  "payment_type": "regular",
  "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 → waiting),
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​

💳 Payment Types​

1️⃣ Regular Payment​

2️⃣ Unscheduled Payment​

🔄 Reusing tokens for future payments​

🔔 Webhook Notifications​

📊 Payment Statuses​

🔧 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

💳 Payment Types

1️⃣ Regular Payment

2️⃣ Unscheduled Payment

🔄 Reusing tokens for future payments

🔔 Webhook Notifications

📊 Payment Statuses