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.
連携完了後、本番環境に移行する前に、以下の受け入れ基準をサンドボックス環境でパスする必要があります。
受け入れ資料の提出
API 連携完了後、該当する受け入れテンプレートをダウンロードして記入してください：
記入済みの受け入れ結果を Waffo の技術連携グループへ提出してください。Waffo は実行済みケース、加盟店取引 ID、Webhook 処理結果、例外処理ロジックを確認します。
機能テスト
決済 (必須)
- 決済成功: 注文作成 → 決済完了 → 注文ステータス更新 → ビジネスロジックが正しく実行される
- 決済失敗: 失敗用テストカードを使用 → 注文ステータス更新 → ビジネスロジックは実行されない
- Webhook 受信: 成功および失敗の通知が正しく処理される
- Webhook の冪等性: 同じ通知を複数回受信した場合、ビジネスロジックは 1 回だけ実行される
返金 (連携している場合)
- 返金成功: 支払い済み注文に対して返金を開始 → ステータスが正しく更新される
- 返金通知: Webhook が到着し、ステータスが正しく更新される
サブスクリプション (連携している場合)
- 初回期間の決済成功 → サブスクリプションがアクティベートされる
- 更新のシミュレーション: サンドボックスの管理画面から次期課金をトリガー → ビジネスロジックが正しく処理される
- サブスクリプションのキャンセル → ステータスが正しく更新される
ワンタイム決済の受け入れケース
実際の連携範囲に合わせて以下のケースを実行し、テンプレートに結果と加盟店取引 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) を設定する
