> ## 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.
# Waffo Checkout でのカード登録
> Waffo Checkout で CIT を完了し、以降の MIT に使用できるカード Token を生成します。
Waffo Checkout でカード会員起点取引（CIT）を完了し、その決済で使用したカードを以降の加盟店起点取引（MIT）用の Token に変換します。加盟店のページとバックエンドは平文カード情報を扱いません。
## このフローが適しているケース
Waffo Checkout をすでに導入しており、初回決済後に同じユーザーへ次の請求を行う場合に使用します。
* 合意済みの固定スケジュールで行う scheduled MIT
* ユーザーがオフラインのときに行う unscheduled MIT
* 加盟店が課金スケジュールを管理し、`ONE_TIME_PAYMENT` で行う継続請求
今回の決済とは別にカードだけを登録する場合や、独自ページにカード登録 UI を設ける場合は、[加盟店側のカード登録](/docs/ja/developer-docs/integration/tokenization/overview)を使用してください。
## エンドツーエンドのシーケンス
```mermaid theme={null}
sequenceDiagram
actor User as ユーザー
participant Merchant as 加盟店バックエンド
participant Waffo
participant Checkout as Waffo Checkout
participant Channel as 決済チャネル
Merchant->>Waffo: POST /api/v1/order/create
setupFutureUsage=true
Waffo-->>Merchant: 注文作成レスポンス
data.orderStatus + data.orderAction
Merchant-->>User: Waffo Checkout へリダイレクト
User->>Checkout: 新しいカードを入力して送信
Checkout->>Waffo: 支払方法を送信
Waffo->>Channel: CIT を開始
Channel-->>Waffo: 決済成功
Waffo->>Waffo: 以降の利用向け Token を生成
Waffo-->>Merchant: PAYMENT_NOTIFICATION Webhook
paymentInfo.userPaymentAccessToken
opt 決済結果を照会
Merchant->>Waffo: POST /api/v1/order/inquiry
Waffo-->>Merchant: 注文照会レスポンス
data.orderStatus + data.paymentInfo.userPaymentAccessToken
end
Merchant->>Merchant: Token を保存
Note over Merchant,Waffo: 加盟店は MIT ホワイトリストで承認済み
Merchant->>Waffo: POST /api/v1/order/create
userPaymentAccessToken + merchantInitiatedMode
Waffo-->>Merchant: 注文作成レスポンス
data.orderStatus
Waffo->>Channel: Token を使用して MIT を開始
Channel-->>Waffo: MIT 結果
Waffo-->>Merchant: PAYMENT_NOTIFICATION Webhook
MIT 結果
opt MIT の結果を照会
Merchant->>Waffo: POST /api/v1/order/inquiry
Waffo-->>Merchant: 注文照会レスポンス
data.orderStatus
end
```
## 加盟店側のカード登録との違い
| 比較項目 | Waffo Checkout でのカード登録 | 加盟店側のカード登録 |
| ----------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| エントリーポイント | `POST /api/v1/order/create` で `paymentInfo.setupFutureUsage: true` を指定 | `POST /api/v1/tokenization/generate` + `sdk.tokenizationSubmit()` |
| ユーザーの目的 | 決済を完了し、以降の MIT 用 Token を生成 | 同じフローで通常決済を行わずにカードを登録 |
| カード入力画面 | Waffo がホストする Checkout | `@waffo/payment-sdk` を使用する加盟店ページ |
| 導入コスト | 低い。既存の Checkout 決済フローを再利用し、`setupFutureUsage` と Token 結果の処理を追加 | 高い。Tokenization API、フロントエンド SDK、0 円 CIT 検証、Token ステータス通知を実装 |
| 初回検証 | 成功した CIT で支払方法を検証 | 先にカードを登録し、その後 0 円 CIT を作成。3DS はこの CIT でのみ発生する可能性があります |
| Token の取得方法 | `PAYMENT_NOTIFICATION` または注文照会レスポンスの `paymentInfo.userPaymentAccessToken` | Generate リクエストの `notifyUrl` で `TOKENIZATION_NOTIFICATION` を受信 |
## 前提条件
* [Checkout 連携](/docs/ja/developer-docs/integration/checkout/steps)が完了していること。
* 注文で `ONE_TIME_PAYMENT` を使用すること。
* 加盟店アカウントで MIT 対応のカード支払方法が有効であること。`setupFutureUsage: true` を指定すると、Waffo は MIT 対応の支払方法だけを提示します。
* 加盟店が Waffo の MIT ホワイトリストで承認されていること。承認前は MIT を開始できません。
* 同じユーザーには安定した `userInfo.userId` を使用すること。以降に Token を使用するときも同じユーザー ID を指定します。
## 連携手順
[決済作成](/docs/api-reference/order-create/create-new-order)を呼び出し、`paymentInfo` に `setupFutureUsage: true` を設定します。
```json theme={null}
{
"paymentRequestId": "PAY_202609160001",
"merchantOrderId": "ORDER_202609160001",
"orderCurrency": "HKD",
"orderAmount": "100.00",
"orderDescription": "Initial payment with card binding",
"orderRequestedAt": "2026-09-17T02:00:00.000Z",
"notifyUrl": "https://merchant.example.com/webhooks/payment",
"successRedirectUrl": "https://merchant.example.com/payment/success",
"failedRedirectUrl": "https://merchant.example.com/payment/failed",
"merchantInfo": {
"merchantId": "YOUR_MERCHANT_ID"
},
"userInfo": {
"userId": "USER_001",
"userEmail": "user@example.com",
"userTerminal": "WEB",
"userCountryCode": "HKG"
},
"paymentInfo": {
"productName": "ONE_TIME_PAYMENT",
"setupFutureUsage": true
}
}
```
`paymentInfo.setupFutureUsage` と `paymentInfo.userPaymentAccessToken` を同時に指定しないでください。前者は新しい Token を作成し、後者は既存の Token を使用します。
通常の Checkout 決済と同様にレスポンスの `orderAction` を解析し、ユーザーを Waffo Checkout へリダイレクトします。ユーザーは新しいカードを入力して決済を完了します。
ユーザーが既存の保存済みカードを選択した場合、Waffo は同じカードを再登録せずに既存のカードを再利用します。
Waffo Checkout でのカード登録では `TOKENIZATION_NOTIFICATION` は送信されません。決済成功後、Waffo は注文の `notifyUrl` に `PAYMENT_NOTIFICATION` を送信します。生成された Token は `result.paymentInfo.userPaymentAccessToken` から取得します。
このフローで使用するフィールドに絞った決済通知の例：
```json theme={null}
{
"eventType": "PAYMENT_NOTIFICATION",
"result": {
"paymentInfo": {
"userPaymentAccessToken": "TOKEN_xxxxxxxxxxxx"
}
}
}
```
決済成功後に `result.paymentInfo.userPaymentAccessToken` を保存します。決済通知が届かない場合は [`POST /api/v1/order/inquiry`](/docs/api-reference/order-inquiry/order-inquiry) を呼び出し、`paymentRequestId` または `acquiringOrderId` を指定して、レスポンスの同じフィールドを参照してください。例：
```json theme={null}
{
"paymentRequestId": "PAY_202609160001"
}
```
`TOKENIZATION_NOTIFICATION` を待つ必要はありません。
MIT を開始できるのは、Waffo の MIT ホワイトリストで承認された加盟店だけです。承認前は scheduled と unscheduled のどちらの MIT も開始できません。
以降の請求では、決済通知で取得した Token を `paymentInfo.userPaymentAccessToken` として渡し、`merchantInitiatedMode` を設定します。
```json theme={null}
{
"paymentRequestId": "MIT_202610160001",
"merchantOrderId": "ORDER_202610160001",
"orderCurrency": "HKD",
"orderAmount": "49.00",
"orderDescription": "Scheduled merchant-initiated payment",
"orderRequestedAt": "2026-10-16T02:00:00.000Z",
"notifyUrl": "https://merchant.example.com/webhooks/payment",
"merchantInfo": {
"merchantId": "YOUR_MERCHANT_ID"
},
"userInfo": {
"userId": "USER_001",
"userEmail": "user@example.com",
"userTerminal": "WEB"
},
"paymentInfo": {
"productName": "ONE_TIME_PAYMENT",
"userPaymentAccessToken": "TOKEN_xxxxxxxxxxxx",
"merchantInitiatedMode": "scheduled"
}
}
```
`merchantInitiatedMode` では次の値を使用できます。
* `scheduled`：事前に合意した固定スケジュールで請求
* `unscheduled`：固定周期のない加盟店起点の請求
## トラブルシューティング
### 利用可能な支払方法がない
`setupFutureUsage: true` を指定すると、Waffo は MIT 非対応の支払方法を除外します。加盟店アカウントに MIT 対応のカード契約があることを確認してください。対象が残らない場合は、Waffo テクニカルサポートへお問い合わせください。
### 決済は成功したが Token が届かない
`PAYMENT_NOTIFICATION` を受信しているか確認し、`result.paymentInfo.userPaymentAccessToken` を参照してください。通知が届かない場合は Order Inquiry で同じフィールドを取得します。Waffo Checkout でのカード登録では `TOKENIZATION_NOTIFICATION` は送信されません。
### MIT を開始できない
加盟店が Waffo の MIT ホワイトリストで承認されていることを確認してください。Token を取得済みでも、承認前は scheduled または unscheduled MIT を開始できません。