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: "[email protected]",
    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)

const payload = {
  country: "VN"
}

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": "[email protected]",
  "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