> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helloclever.co/llms.txt
> Use this file to discover all available pages before exploring further.

# カード JavaScript SDK の連携

> Hello Clever の JavaScript SDK で、チェックアウトに AUD と USD のカード決済を組み込みます。セットアップ、初期化、決済の作成、コールバック、トークンの再利用を説明します。

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

このガイドでは、セットアップ、初期化、決済の作成、コールバックの処理を説明します。

> [!NOTE]
>
> 対応通貨：**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 の動作は[デモサイト](https://demo-getkollo-five.vercel.app)で確認できます。

## 連携の手順

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

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

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

```html theme={null}
<script
  src="https://cdn.lightningpay.me/media/getkollo-sdk/1.1.0/sandbox/getkollo.js"
  async
></script>
```

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

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

```html theme={null}
<div class="get-kollo"></div>
```

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

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

```javascript theme={null}
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 | はい | アプリケーション固有の識別子です。 |

```javascript theme={null}
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` です。[決済の種類](#payment-types)を参照してください。 |

#### `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)` は読み込み状態を通知するため、外部ボタンの状態管理に使えます。 |

```javascript theme={null}
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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)）です。 |

```javascript theme={null}
const payload = {
  country: "AU",
};

getKolloSDK.onSubmit(payload);
```

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

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

```javascript theme={null}
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` です。 |

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

## 決済の種類

### 通常の決済（regular）

顧客は決済の際にカード情報の保存を選択できます。保存したカード情報は、顧客が再入力することなく将来の決済に使えます。

**SCA の要件：** 強力な顧客認証（SCA）が必要な地域では、顧客は決済の際に 3D セキュア（3DS）の認証を完了する必要があります。SCA が必要な場合、API のレスポンスに `pay_code.3ds_url` のフィールドが含まれます。認証を完了するため、顧客をこの URL へリダイレクトしてください。

**通常の決済を設定する：** `createPayment()` を呼び出す際に、`order` のオブジェクトで `payment_type: "regular"` を渡します。既定値が `regular` のため、指定は任意です。

```javascript theme={null}
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 認証は不要です。

**不定期の決済を設定する：**

**1. 最初の決済（SDK）**

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

```javascript theme={null}
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);
```

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

[Create Payment via Tokenisation](/api/cards/create-payment-via-tokenisation) で、保存済みのトークンに次のフィールドを指定して請求します。

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

```json Request theme={null}
{
  "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"
  }
}
```

```json Response theme={null}
{
  "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](/api/cards/create-payment-via-tokenisation) を呼び出します。`payment_type` を省略した場合の既定値は `regular` です。`regular` と `unscheduled` の違いは[決済の種類](#payment-types)を参照してください。

```json Request theme={null}
{
  "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"
  }
}
```

```json Response theme={null}
{
  "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` のオブジェクトが含まれます。

```json theme={null}
{
  "token": {
    "id": "tok_dfe1988a1ffc0d6562d3",
    "type": "card"
  }
}
```

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

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

## 決済のステータス

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


## Related topics

- [カード決済 API の概要](/ja/api/card/overview.md)
- [カード決済の受け付けと管理](/ja/developer-reference/api-use-cases/issue-and-manage-cards.md)
- [カード決済のセキュリティと 3DS2](/ja/security/card-security.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.