> ## 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 連携完了後に満たすべき受け入れ基準。機能テスト、例外処理、パラメーター要件、データ完全性を含みます。
連携完了後、本番環境に移行する前に、以下の受け入れ基準をサンドボックス環境でパスする必要があります。
## 受け入れ資料の提出
API 連携完了後、連携段階に応じた受け入れテンプレートをダウンロードして記入してください：
* ワンタイム決済の初回連携：ワンタイム決済受け入れテンプレート
* サブスクリプション決済の初回連携：サブスクリプション受け入れテンプレート
* 初回ではないワンタイム決済の追加連携：ワンタイム決済の追加連携受け入れテンプレート
このテンプレートは `ONE_TIME_PAYMENT` に適用されます。少なくとも1回の連携受け入れを完了しており、今回が初回ではない追加連携の場合にのみ使用してください。初回連携では使用せず、プロダクトに応じて標準のワンタイム決済またはサブスクリプション決済テンプレートを選択してください。
記入済みの受け入れ結果を Waffo の技術連携グループへ提出してください。Waffo は実行済みケース、加盟店取引 ID、Webhook 処理結果、例外処理ロジックを確認します。
> **補足**: 受け入れテンプレート内の一部の例外ケースは、サンドボックス専用の特殊金額で再現します。サンドボックス環境でこれらの金額を渡すと、API は対応するエラーを意図的に返します。詳細は [サンドボックスシミュレーター](/docs/ja/developer-docs/tools-and-references/developer-tools/sandbox-simulator) を参照してください。
## 機能テスト
### 決済 (必須)
* 決済成功: 注文作成 → 決済完了 → 注文ステータス更新 → ビジネスロジックが正しく実行される
* 決済失敗: 失敗用テストカードを使用 → 注文ステータス更新 → ビジネスロジックは**実行されない**
* Webhook 受信: 成功および失敗の通知が正しく処理される
* Webhook の冪等性: 同じ通知を複数回受信した場合、ビジネスロジックは 1 回だけ実行される
### 返金 (連携している場合)
* 返金成功: 支払い済み注文に対して返金を開始 → ステータスが正しく更新される
* 返金通知: Webhook が到着し、ステータスが正しく更新される
### サブスクリプション (連携している場合)
* 初回期間の決済成功 → サブスクリプションがアクティベートされる
* 更新のシミュレーション: サンドボックスの管理画面から次期課金をトリガー → ビジネスロジックが正しく処理される
* サブスクリプションのキャンセル → ステータスが正しく更新される
### 連携範囲に応じた検証
実際に連携している機能のみ検証してください。未連携の機能は対象外とします。手動または Waffo の支援が必要なケースには理由、証拠、次の対応を記録し、未実行を合格にしないでください。
以下の検証 ID は AI 連携検証と共通です。`P` はワンタイム決済テンプレート、`S` はサブスクリプションテンプレートを示します。既存のケース番号は変更せず、新規ケースには `SDK-` 接頭辞を使用します。
| 検証 ID | SDK API または Webhook イベント | Excel ケース |
| - | - | - |
| `order-create` | `order.create` | P `1.1` |
| `order-inquiry` | `order.inquiry` | P `2.2` |
| `order-cancel` | `order.cancel` | P `4.1` |
| `order-capture` | `order.capture` | P `SDK-P01` |
| `refund-success` | `order.refund` | P `5.1` |
| `refund-inquiry` | `refund.inquiry` | P `6.2` |
| `subscription-create` | `subscription.create` | S `1.1` |
| `subscription-inquiry` | `subscription.inquiry` | S `2.2` |
| `subscription-cancel` | `subscription.cancel` | S `SDK-S07` |
| `subscription-update` | `subscription.update` | S `SDK-S01` |
| `subscription-manage` | `subscription.manage` | S `SDK-S02` |
| `subscription-change` | `subscription.change` | S `SDK-S03` |
| `subscription-change-inquiry` | `subscription.changeInquiry` | S `SDK-S04` |
| `merchant-config-inquiry` | `merchantConfig.inquiry` | P `SDK-P02` |
| `pay-method-coverage` | `payMethodConfig.inquiry` | P `SDK-P03` |
| `wallet-inquiry` | `wallet.inquiry` | P `SDK-P04` |
| `payment-success` | `PAYMENT_NOTIFICATION` / `onPayment` | P `3.1` |
| `refund-webhook` | `REFUND_NOTIFICATION` / `onRefund` | P `7.1` |
| `subscription-event-status` | `SUBSCRIPTION_STATUS_NOTIFICATION` / `onSubscriptionStatus` | S `3.1` |
| `subscription-event-period-changed` | `SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION` / `onSubscriptionPeriodChanged` | S `SDK-S05` |
| `subscription-event-change` | `SUBSCRIPTION_CHANGE_NOTIFICATION` / `onSubscriptionChange` | S `SDK-S06` |
* Capture：capture 対応の承認済み注文に `order.capture` を呼び出し、`captureAmount`、注文 ID、`orderStatus` を記録します。照会で金額と状態の一致を確認し、失敗や不明状態では商品を提供しません。重複リクエストで二重に履行しないことを確認します。
* 加盟店と決済方法の設定：現在の MID で設定を照会し、契約済み決済方法、国、`currency` を確認します。利用可能な方法からテストを選び、認証情報ではなくマスクした応答を保存します。
* 入金先アドレスの照会：`network`、`asset`、`payTo` が要求したネットワーク、通貨、プラットフォームの入金先と一致することを確認します。加盟店が指定したアドレスで応答を置き換えないでください。
* サブスクリプション更新：`subscriptionRequest` と `subscriptionId` の両方で更新し、`amount`、`scheduledAmounts`、該当する `trialPeriodAmount` を検証します。管理 URL から Sandbox の後続対象周期をシミュレートし、整数の `paymentDetails: 1` で照会します。対象 `period` の `orderAmount` を更新計画と数値で比較してください。更新応答のみでは適用を証明できません。
* サブスクリプション管理：`managementUrl`、`expiredAt`、対象 ID を確認します。有効期限内に URL を開き、別ユーザーのサブスクリプションにアクセスしないことを確認します。
* 変更と変更照会：`originSubscriptionRequest`、新しい `subscriptionRequest`、`subscriptionId` を保存します。`AUTHORIZATION_REQUIRED` の場合は認証を完了してから終端状態、計画、後続周期の実際の金額を照会します。
* 周期変更通知：署名、サブスクリプション ID、周期、金額を検証し、`onSubscriptionPeriodChanged` を呼び出します。重複通知で特典を二重に付与しないことを確認します。
* サブスクリプション変更通知：署名を検証し、旧と新のサブスクリプションを関連付けて `onSubscriptionChange` を呼び出します。成功時のみ確認済みルールで特典を変更し、失敗や重複通知で新しい特典を付与しません。
***
## ワンタイム決済の追加連携受け入れケース
初回ではないワンタイム決済の追加連携でのみ、このテンプレートを使用してください。ダウンロード後：
1. `0.前置条件` ワークシートに、加盟店名、MID、契約プロダクト、契約済み決済手段、今回連携する API の一覧を記入します。
2. `1.集成验收用例` ワークシートで今回の連携範囲に該当するケースを実行し、実行有無、加盟店取引 ID、加盟店取引時刻を記録します。
このテンプレートは、オーダー決済の成功と失敗、決済結果通知、オーダーキャンセル、返金、返金結果通知を対象とします。キャンセルと返金のケースは、今回の連携に該当 API が含まれる場合のみ実行してください。
***
## ワンタイム決済の受け入れケース
実際の連携範囲に合わせて以下のケースを実行し、テンプレートに結果と加盟店取引 ID を記録してください。
### 必須ケース
* オーダー作成後に決済成功をシミュレートし、加盟店の `notifyUrl` が終端成功通知を受信し、`paymentRequestId`、`orderCurrency`、`orderAmount` が加盟店オーダーと一致することを確認する
* オーダー作成後に決済失敗をシミュレートし、加盟店の `notifyUrl` が終端失敗通知を受信し、オーダー情報が一致することを確認する
* 決済成功後にオーダーを照会し、`orderStatus = PAY_SUCCESS` を確認する
* 決済失敗後にオーダーを照会し、`orderStatus = ORDER_CLOSE` を確認する
* 決済成功通知は署名検証が通った後に加盟店側ステータスを更新する
* 決済失敗通知では商品発送や権益付与のビジネスロジックを実行しない
* 通知の署名検証に失敗した場合、その通知は処理せず、照会 API でオーダー状態を取得する
### 例外ケース
* チャネル拒否：`C0005 Payment Channel Rejection` をシミュレートする
* 冪等性競合：同じ `paymentRequestId` に異なる金額または通貨を使用し、`A0011` を確認する
* システム利用不可：`C0001 System Error` をシミュレートする
* Unknown Status：`E0001 Unknown Status` をシミュレートし、加盟店側で独自にオーダーを閉じず、照会結果または Webhook 通知を待つ
### 条件付きケース
* キャンセルを連携している場合：決済前にキャンセルし、`ORDER_CLOSE` を確認する
* キャンセルを連携している場合：決済成功後のキャンセルで `A0013` を確認する
* 返金を連携している場合：返金成功後に `refundRequestId`、`refundAmount`、返金ステータスを確認する
* 返金照会または返金通知を連携している場合：返金中、全額返金、部分返金、返金失敗の各状態を確認する
## サブスクリプション決済の受け入れケース
実際の連携範囲に合わせて以下のケースを実行し、テンプレートに結果、加盟店取引 ID、加盟店取引時間を記録してください。
### 必須ケース
* サブスクリプション作成後に初回決済成功をシミュレートし、サブスクリプション状態通知とサブスクリプション決済通知を受信する
* サブスクリプション作成後に初回決済失敗をシミュレートし、失敗通知と失敗リダイレクトを確認する
* 未決済サブスクリプションを照会し、`subscriptionAction` または `orderAction` に従ってユーザーを認可へ誘導できる
* 成功したサブスクリプションを照会し、ステータスが `ACTIVE` であることを確認する
* 失敗したサブスクリプションを照会し、クローズ済みの終端状態であることを確認する
* サブスクリプション状態通知の署名検証後、`subscriptionRequest`、金額、通貨、周期、試用期間項目が加盟店記録と一致することを確認する
* サブスクリプション決済通知の署名検証後、`subscriptionRequest` と `period` に基づいて該当周期の決済オーダーを照合する
* 通知の署名検証に失敗した場合、ローカル状態を更新せず、照会 API で実際の状態を取得する
### 更新とキャンセル
* サブスクリプション管理ページで次期決済成功をシミュレートし、更新決済通知を確認する
* サブスクリプション管理ページで次期決済失敗をシミュレートし、失敗した更新通知を確認する
* 加盟店側キャンセルを連携している場合、キャンセル後に `MERCHANT_CANCELLED` を確認する
* チャネル側キャンセルをサポートする場合、`CHANNEL_CANCELLED` 通知を処理できる
### 例外ケース
* サブスクリプションチャネル拒否：`C0005 Payment Channel Rejection` をシミュレートする
* 冪等性競合：同じリクエスト ID に異なる金額または通貨を使用し、`A0011` を確認する
* システム利用不可：`C0001 System Error` をシミュレートする
* Unknown Status：`E0001 Unknown Status` をシミュレートし、加盟店側で独自にサブスクリプションを閉じず、照会結果または Webhook 通知を待つ
* 返金機能をサブスクリプションで再利用する場合、ワンタイム決済の返金ルールに沿って返金、返金照会、返金通知を検証する
***
## 決済手段のカバレッジ
契約中のすべての決済手段を個別にテストする必要はありません。タイプごとに代表を選んでください。
| ルール | 例 |
| - | - |
| カードを少なくとも 1 つ | CC\_VISA |
| 国・タイプごとに少なくとも 1 つ | インドネシアの電子ウォレットの場合、DANA または ShopeePay |
| 特殊パラメーターのある決済手段は必ずテスト | OVO (電話番号が必須)、PIX (CPF が必須) |
| VA を少なくとも 1 つ | BCA\_VA |
| Apple Pay / Google Pay | 実機で手動テストが必要 |
***
## 例外処理の要件
Waffo は受け入れ時に以下の例外シナリオに対する処理ロジックを確認します。
| シナリオ | 対応すべき内容 |
| - | - |
| Unknown Status (E0001) | **注文をクローズしない**。同じパラメーターで再試行し、それでも失敗する場合は照会結果または Webhook 通知を待つ |
| チャネル拒否 / システム利用不可 | ユーザーに分かりやすいメッセージを表示し、再試行または別の決済手段への切り替えを案内する |
| Webhook 署名検証失敗 | 通知を処理せず、照会 API で正しいステータスを取得する |
| 冪等性の競合 (A0011) | 各リクエストは独立して生成された ID (paymentRequestId / refundRequestId / subscriptionRequest) を使用する |
***
## パラメーター要件
| フィールド | 要件 |
| - | - |
| 金額 | 文字列型 (例: `"100.00"`)。浮動小数点ではありません |
| `orderDescription` | 正確な説明を指定すること。「test」などのプレースホルダーは使用しない |
| `goodsName` | 必須 |
| `goodsUrl` または `appName` | どちらか一方以上を指定 (コンプライアンスおよびリスクコントロール要件) |
| `userEmail` | 実際のメールアドレス、または `userId@examples.com` 形式 (「test」などの文字列を避け、ユーザー間で共用しない) |
| 時刻フィールド | UTC+0、末尾は `Z`、ミリ秒は 3 桁以内 |
***
## データ完全性
* `paymentRequestId` は API 呼び出しの**前**に永続化する (ネットワークタイムアウト時に照会で復旧できるように)
* `acquiringOrderID` は決済成功後に保存する
* リダイレクト URL (successRedirectUrl / failedRedirectUrl) を設定する
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.