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

# カードバインドとトークン管理

> ユーザーの銀行カード情報を安全にトークン化し、以降の決済時にカード番号の再入力を不要にします。

ユーザーの銀行カード情報を安全にトークン化することで、以降の決済時にカード番号を再入力する必要がなくなります。

<Info>
  このフローは**サーバー側**（Generate / Inquiry / Remove API の呼び出し）と**フロントエンド**（`@waffo/payment-sdk` によるカード情報の送信）の両方にまたがります。
</Info>

## 主要なフロー

```
1. 加盟店バックエンド → Generate API を呼び出し → tokenSessionId を取得
2. フロントエンド → @waffo/payment-sdk を使用してカード情報を送信 → カードデータを暗号化して送信
3. 処理結果 → tokenId を取得（3DS 認証が必要な場合あり）
4. 以降の決済 → order/create に tokenId を渡してカード番号の代わりに使用
```

## カードバインドフロー

<Steps>
  <Step title="加盟店バックエンドから Generate API を呼び出す">
    `POST /api/v1/tokenization/generate` を呼び出し、`tokenRequestId`、`merchantUserId`、`tokenType: "CARD"` などのパラメータを渡します。成功すると `tokenSessionId` が返されます。

    詳細は [Generate API](/docs/ja/developer-docs/integration/tokenization/generate) を参照してください。
  </Step>

  <Step title="フロントエンドからカード情報を送信する">
    `@waffo/payment-sdk` の `tokenizationSubmit` メソッドを使用して、カードデータを暗号化し Waffo サーバーに送信します：

    ```typescript theme={null}
    import WaffoSDK from '@waffo/payment-sdk';

    const sdk = new WaffoSDK('your-client-api-key', {
      env: 'prod',
      locale: 'en'
    });

    const result = await sdk.tokenizationSubmit('tokenSessionId', {
      tokenData: {
        pan: '4111111111111111',
        name: 'John Doe',
        expiry: '12/2025',    // MM/YYYY
        cvv: '123'            // 可选
      },
      billingAddress: {        // 可选
        countryCode: 'USA',
        region: 'CA',
        city: 'San Francisco',
        postalCode: '94102',
        address: '123 Main St'
      }
    });
    ```

    SDK がカードデータを自動的に暗号化するため、加盟店サーバーはカード番号の平文に触れる必要がなく、PCI DSS 認証も不要です。
  </Step>

  <Step title="カードバインド結果のハンドリング">
    ```typescript theme={null}
    if (result.success) {
      const { tokenRequestId, validateUrl } = result.data;

      if (validateUrl) {
        // 需要 3DS 验证，重定向用户
        window.location.href = validateUrl;
      } else {
        // 绑卡成功，等待 Webhook 获取 tokenId
      }
    }
    ```

    カードバインド完了後、Waffo は `notifyUrl` を通じて加盟店バックエンドに通知を送信し、最終的な `tokenId` を含みます。加盟店はこの `tokenId` を保存し、以降の決済に使用する必要があります。
  </Step>
</Steps>

### 代替案：PCI-DSS 加盟店による直接送信

加盟店が PCI-DSS 認証を取得している場合、フロントエンド SDK を使用せずに、Generate API の `tokenData` フィールドを通じてバックエンドから直接カード番号などの機微情報を送信できます。この場合、API は `tokenId` を直接返します。

## トークンを使用して決済する

`tokenId` を取得した後、注文作成時に渡すことでカード番号の代わりに使用します：

```typescript theme={null}
const response = await waffo.order().create({
  paymentRequestId: '...',
  merchantOrderId: 'ORDER_001',
  orderCurrency: 'HKD',
  orderAmount: '100.00',
  tokenId: 'tok_xxxxxxxxxxxx',  // 使用 Token 代替卡号
  notifyUrl: 'https://your-site.com/webhook',
  // ... 其他参数
});
```

ワンタイム決済（ONE\_TIME\_PAYMENT）およびサブスクリプション決済（SUBSCRIPTION）をサポートしています。

## トークン管理

| 操作 | API                                                                                      | 説明                    |
| -- | ---------------------------------------------------------------------------------------- | --------------------- |
| 照会 | [POST /api/v1/tokenization/inquiry](/docs/ja/developer-docs/integration/tokenization/inquiry) | ユーザーがバインド済みのトークン一覧を取得 |
| 削除 | [POST /api/v1/tokenization/remove](/docs/ja/developer-docs/integration/tokenization/remove)   | バインド済みトークンを削除         |

## セキュリティメカニズム

* フロントエンド SDK がカードデータを自動的に暗号化。加盟店サーバーはカード番号の平文に触れない
* すべての API リクエストとレスポンスで SHA256WithRSA 署名検証を使用
* 3DS 認証をサポートし、決済のセキュリティを強化
* PCI-DSS 非認証の加盟店は**必ず**フロントエンド SDK を使用する必要があり、バックエンドから直接カード番号を渡すことはできません