Hello Clever Developer Docs

JavaScript SDK を使うと、わずかなコードでチェックアウトのフローにカード決済を安全に組み込めます。カードのフォームは Hello Clever が iframe 内に描画するため、生のカード情報がフロントエンドやサーバーに触れることはありません。このガイドでは、セットアップ、初期化、決済の作成、コールバックの処理を説明します。

対応通貨：AUD と USD。

環境

環境	スクリプトの URL
サンドボックス	`https://cdn.lightningpay.me/media/getkollo-sdk/1.1.0/sandbox/getkollo.js`
本番環境	`https://cdn.lightningpay.me/media/getkollo-sdk/1.1.0/prod/getkollo.js`

SDK の動作はデモサイトで確認できます。

連携の手順

アプリ ID とドメインを登録する

Hello Clever のチームに連絡してドメインを登録し、app_id を受け取ります。

チェックアウトページに SDK のスクリプトを読み込む

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

本番稼働の際は、本番環境のスクリプトの URL に切り替えてください。

HTML にマウント用の要素を追加する

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

SDK はこの要素に決済の iframe を挿入します。createPayment() を呼び出す前に、この要素が存在している必要があります。

SDK を初期化して決済を作成する

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@example.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 の設定リファレンス

`GetKollo({ app_id })`

SDK のインスタンスを作成します。

フィールド	型	必須	説明
`app_id`	string	はい	アプリケーション固有の識別子です。

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

const init = await getKolloSDK.initialize();

`createPayment(order, options)`

決済を作成し、マウント用の要素にカードのフォームを描画します。

`order`（必須）

フィールド	型	必須	説明
`external_id`	string	はい	注文の一意の識別子です。
`customer_name`	string	いいえ	顧客の名前です。
`customer_email`	string	いいえ	顧客のメールアドレスです。
`amount`	number	はい	取引金額（セント単位）です。
`currency`	string	はい	`USD` または `AUD` です。
`return_url`	string	いいえ	成功または失敗の後のリダイレクト先の URL です。
`payment_type`	enum	いいえ	`regular` または `unscheduled` です。既定値は `regular` です。決済の種類を参照してください。

`options`（必須）

フィールド	型	必須	説明
`mountElement`	string	はい	iframe を配置する要素の CSS セレクター（クラスまたは ID）です。
`styleProps.frame.width`	string	いいえ	iframe の幅です。既定値は `500px` です。
`styleProps.frame.height`	string	いいえ	iframe の高さです。既定値は `500px` です。
`paymentButton`	enum	いいえ	`iframe`（既定値）は iframe 内の決済ボタンを使います。`external` では iframe の外に独自のボタンを配置でき、そのボタンがクリックされたときに `getKolloSDK.onSubmit()` を呼び出す必要があります。
`events`	object	いいえ	イベントハンドラーです。`onReady()` は決済フォームの読み込みが完了し、入力を受け付けられる状態になったときに発火します。`onLoading(isLoading)` は読み込み状態を通知するため、外部ボタンの状態管理に使えます。

const order = {
  external_id: "order-001",
  customer_name: "John Doe",
  customer_email: "john.doe@example.com",
  amount: 1000,
  currency: "USD", // USD or AUD
  return_url: "https://yourdomain.com/success", // optional redirect URL
  payment_type: "regular", // optional: "regular" | "unscheduled"
};

const options = {
  mountElement: ".get-kollo", // element class name or ID
  styleProps: {
    frame: {
      width: "100%",
      height: "100%",
    },
  },
  paymentButton: "iframe",
  events: {
    // Fires when the payment form is fully loaded and ready for input.
    onReady: () => {
      console.log("Payframe is ready.");
    },
    // With paymentButton: "external", use this to manage your button's loading state.
    onLoading: (isLoading) => {
      console.log(`Payframe loading state: ${isLoading}`);
    },
  },
};

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

`onSubmit(payload)`

paymentButton が external の場合に、カードのフォームを送信します。独自のボタンのクリックハンドラーから呼び出してください。

フィールド	型	必須	説明
`country`	string	はい	2 文字の国コード（ISO 3166-1 alpha-2）です。

const payload = {
  country: "AU",
};

getKolloSDK.onSubmit(payload);

決済ステータスのコールバック

決済が送信された後、またはカードのフォームの描画に失敗した場合に、SDK は window.getkolloCardCallback を呼び出します。

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

フィールド	説明
`status`	`succeeded` または `failed` です。
`error`	`message` と `code` を持つエラーのオブジェクトです。`card_init_timeout` のコードは、カードのフォームの描画に失敗したことを示します。
`order`	SDK に渡した注文のオブジェクトです。
`type`	常に `callback` です。

コールバックはブラウザ上で起きたことを反映します。注文を処理する前に、Webhook の通知で最終的な決済ステータスを確認してください。

決済の種類

通常の決済（regular）

顧客は決済の際にカード情報の保存を選択できます。保存したカード情報は、顧客が再入力することなく将来の決済に使えます。 SCA の要件： 強力な顧客認証（SCA）が必要な地域では、顧客は決済の際に 3D セキュア（3DS）の認証を完了する必要があります。SCA が必要な場合、API のレスポンスに pay_code.3ds_url のフィールドが含まれます。認証を完了するため、顧客をこの URL へリダイレクトしてください。 通常の決済を設定する： createPayment() を呼び出す際に、order のオブジェクトで payment_type: "regular" を渡します。既定値が regular のため、指定は任意です。

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

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

不定期の決済（unscheduled）

不定期の決済の合意があれば、最初の取引で顧客のカード情報を保存し、後日その保存済みカードでカード非対面の取引を行えます。たとえば、顧客がホテルのチェックイン時にカード情報を提供し、チェックアウト時に初めて請求されるケースです。その時点で追加の料金が発生している場合があります。 SCA の要件： マーチャント起点の取引は SCA の対象外で、Merchant Initiated Exclusion の適用を受けるため、3DS 認証は不要です。 不定期の決済を設定する：

最初の決済（SDK）

createPayment() を呼び出す際に、order のオブジェクトで payment_type: "unscheduled" を渡します。これにより顧客のカード情報が保存されます。

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

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

以降の決済（トークン化 API）

Create Payment via Tokenisation で、保存済みのトークンに次のフィールドを指定して請求します。

payment_type：unscheduled を設定します。
previous_payment_uuid：最初の決済で返された uuid です。元の SCA 認証済みの取引を参照し、承認率を高めます。
charge_reason：承認率とチャージバックの処理を改善するため、指定を推奨します。次のいずれかを使います。
- resubmission：元の購入は成立したものの、商品やサービスの提供時にオーソリを取得できなかった場合。
- delayed_charge：遅延した請求がある場合。
- no_show：カード会員が購入に合意したものの、合意の条件を満たさなかった場合。
- reauthorisation：元の購入の後に追加の購入があった場合。通常は遅延した注文や分割された注文に使います。

{
  "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"
  }
}

{
  "uuid": "7PPPMXIGH",
  "name": "Testing",
  "email": "john.doe@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"
}

将来の決済でトークンを再利用する

保存済みのトークン（token.id と token.type）を指定して Create Payment via Tokenisation を呼び出します。payment_type を省略した場合の既定値は regular です。regular と unscheduled の違いは決済の種類を参照してください。

{
  "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"
  }
}

{
  "uuid": "7PPPMXIGH",
  "name": "Testing",
  "email": "john.doe@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://merchant.com/webhook",
    "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"
}

レスポンスに pay_code.3ds_url が含まれる場合は、3DS を完了するため顧客をその URL へリダイレクトしてください。オーソリの後、顧客は return_url へ戻ります。

Webhook の通知

決済のステータスが変わると（たとえば pending から authorised、さらに waiting へ）、Hello Clever は設定済みのエンドポイントへ Webhook のイベントを送信します。決済が authorised または waiting に達すると、Webhook に token のオブジェクトが含まれます。

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

token.id はデータベースに安全に保存してください。顧客がカード情報を再入力することなく、将来の決済に再利用できます。

ペイロードの構造、オーソリ後のトークンの付与、セットアップ、Webhook のセキュリティについては Webhook を参照してください。

決済のステータス

ステータス	意味
`pending`	顧客が決済を開始したものの、まだ進めていません。
`authorised`	決済がオーソリされ、キャプチャできる状態です。
`waiting`	決済が承認され、精算を待っています。
`received`	資金を受け取りました。
`expired`	完了前に決済のセッションが期限切れになりました。
`return_pending`	返金がリクエストされ、処理を待っています。
`partially_refunded`	顧客に一部返金が行われました。
`return_received`	全額が顧客に返金されました。
`return_expired`	返金が期限切れになりました（10 日後）。
`return_rejected`	返金のリクエストが拒否されました。
`failed`	エラーまたは拒否により決済が失敗しました。
`in_dispute`	顧客が異議を申し立て、審査中です。
`dispute_lost`	異議が顧客に有利な形で解決されました。

基本

決済 API

Card API

Cashback API

Reporting API

カード JavaScript SDK の連携

環境

連携の手順

SDK の設定リファレンス

`GetKollo({ app_id })`

`createPayment(order, options)`

`order`（必須）

`options`（必須）

`onSubmit(payload)`

決済ステータスのコールバック

決済の種類

通常の決済（regular）

不定期の決済（unscheduled）

将来の決済でトークンを再利用する

Webhook の通知

決済のステータス

​環境

​連携の手順

​SDK の設定リファレンス

​GetKollo({ app_id })

​createPayment(order, options)

​order（必須）

​options（必須）

​onSubmit(payload)

​決済ステータスのコールバック

​決済の種類

​通常の決済（regular）

​不定期の決済（unscheduled）

​将来の決済でトークンを再利用する

​Webhook の通知

​決済のステータス

環境

連携の手順

SDK の設定リファレンス

`GetKollo({ app_id })`

`createPayment(order, options)`

`order`（必須）

`options`（必須）

`onSubmit(payload)`

決済ステータスのコールバック

決済の種類

通常の決済（regular）

不定期の決済（unscheduled）

将来の決済でトークンを再利用する

Webhook の通知

決済のステータス