code と msg を返します。コードの先頭の文字が、誰が対応すべきかを示します。
完全な一覧はエラーコードクイックリファレンスにあります。このページでは、最も多くのサポートチケットを生むコードを扱います。
A0001「Invalid Api secret key」が返ります。API キーはどこで入手できますか？
X-API-KEY リクエストヘッダーが欠けているか、貴社アカウントに発行されたキーと一致していません。API キーは加盟店のオンボーディング時に Waffo から提供され、Merchant Portal のダッシュボードで確認できます。
よくある原因：
- 環境の不一致 — サンドボックスと本番は異なる API キーと RSA キーを使用します。サンドボックスのキーを
https://api.waffo.comに送る（または本番のキーをhttps://api-sandbox.waffo.comに送る）とA0001で失敗します。 - リクエストに
X-API-KEYヘッダーがまったく含まれていない。
A0002「Invalid signature」はどのようにデバッグすればよいですか？
Waffo は X-SIGNATURE ヘッダーを、オンボーディング時に交換した加盟店の公開鍵に対して SHA256WithRSA で検証します。検証に失敗するということは、貴社が生成した署名が Waffo が受信したボディと一致していないということです。次のチェックリストを順に確認してください。
- 送信したとおりの生のリクエストボディ文字列に署名してください。JSON としてパースして再度文字列化したり、整形済みや順序を並べ替えたコピーに署名したりしないでください。
- この環境で Waffo に登録済みの公開鍵に対応する秘密鍵で署名していることを確認してください（サンドボックスと本番の RSA キーは別です）。
- アルゴリズムが
SHA256WithRSAであることを確認してください。 - 新しい鍵ペアを生成した場合、切り替える前に新しい公開鍵を Waffo に登録する必要があります。
A0003「Parameter validation failed」は通常何が原因ですか？
A0003 はリクエスト形式の拒否です。msg フィールドに詳細が含まれます。本番サポートで最も頻度の高い原因は次のとおりです。
-
フィールド長の超過。 すべての文字列フィールドには宣言された最大長があります。
/api/v1/order/createで加盟店が最も頻繁に超過するものは次のとおりです。 -
金額の形式。 金額は小数点以下最大 2 桁の文字列です。そして
JPYのような小数なし通貨は整数でなければなりません。実際の本番の例："orderCurrency":"JPY","orderAmount":"200.88"はA0003で拒否され、"201"は受け付けられます。通貨の取り扱いを参照してください。 -
形式の規約 — 時刻はミリ秒付きの ISO 8601（
2023-04-01T03:00:00.000Z）、通貨は ISO 4217、国は ISO 3166-1 alpha-3（IDN、PHL）、userPhoneは+国番号-番号の形式（例：+62-08990013157）です。
A0018 はどういう意味ですか？どう修正しますか？
Acquiring API では、A0018 は 「Payment method in merchant order does not match with current merchant contract」 です。注文内の payMethod/国/プロダクトの組み合わせが、貴社が契約しているものではありません。
修正方法：
/api/v1/paymethodconfig/inquiryを呼び出します。レスポンスには、契約済みのすべての決済手段が、そのproductName（ONE_TIME_PAYMENT/DIRECT_PAYMENT）、payMethodName、country、currentStatus（1利用可、0利用不可）、およびfixedMaintenanceRulesの時間枠とともに列挙されます。- その一覧に
currentStatusが1で現れる組み合わせのみを送信してください。どの決済手段を契約できるかは契約済みの設定によります。追加するには Merchant Portal を確認するか、連携サポートに連絡してください。 - 隣接する 2 つのコードは似ていますが、契約の変更ではなくより精密な指定を求めています：
A0022（productNameを指定してください — 複数のプロダクトが見つかりました）とA0033（決済手段の国を指定してください — 複数の決済手段が見つかりました）。
契約に決済手段は含まれているのに、userCurrency を渡すとなぜ A0018 が返るのですか？
A0018 は通貨ペアの次元でも発生します。orderCurrency → userCurrency の組み合わせ（表示通貨ペア）は、決済手段自体とは独立して契約で有効化されている必要があります。たとえば、orderCurrency=JPY かつ userCurrency=USD の注文は、JPY→USD のペアが契約されていない限り A0018 で拒否されます。カード決済が契約されていてもです。
2 つの解決策：
userCurrencyを省略する。 Waffo のチェックアウトが、現在の為替レートで注文金額をユーザーの現地通貨へ自動的に換算します。- ペアを有効化する。 ユーザーに表示する通貨を自分で固定する必要がある場合は、Waffo の連携サポートに連絡して通貨ペアを契約に追加してください。
金額が原因で注文が拒否されました。限度額はどこで確認できますか？
各決済手段には通貨ごとに独自の最小・最大注文金額があり、一部の組み合わせには通常の通貨ルールに加えて精度のルールがあります（小数なし通貨は整数でなければならず、いくつかの決済手段は通貨が通常許容するより少ない小数桁しか受け付けません）。範囲または精度の外にある金額は、注文作成時に明示的なエラーで拒否されます。 限度額はプログラムから読み取れます。/api/v1/paymethodconfig/inquiry は、契約済みの各決済手段について orderAmountMin と orderAmountMax を、その currency とともに返します。レスポンスは決済手段ごとではなく契約ごとに 1 エントリであるため、同じ決済手段が異なる通貨と異なる限度額で複数回現れることがあります。課金する通貨で照合してください。Merchant Portal にも同じ設定が表示されます。
限度額は契約に依存する固定値です。決済手段を貴社アカウントで契約した時点で設定され、為替レートに応じて変動することはありません。クロスカレンシーの注文でも同様です。貴社に適用される値を確認するには、Merchant Portal の決済手段設定を確認するか、Waffo の連携担当者にお尋ねください。
E0001「Unknown status」を受け取りました。決済は失敗ですか？
いいえ。不明は最終状態ではありません。Exxxxx のエラーは、Waffo 内または第三者システム内で結果がまだ確定していないことを意味します。取引を保留中として扱い、最終的な Success/Failed ステータスを受け取るまで照会（/api/v1/order/inquiry）を続けてください。E コードだけを根拠にユーザーに失敗を表示したり、再課金したりしないでください。
元のリクエストを再試行する際は、同じ paymentRequestId を再利用してください。これが冪等性キーです。異なるパラメータで再利用すると A0011「Idempotent param mismatch error」で失敗します。冪等性を参照してください。
Waffo から同じ通知が繰り返し送られてきます。なぜですか？
貴社のエンドポイントが通知を確認応答していません。繰り返し発生するサポート事例：加盟店の Webhook エンドポイントがContent-Type: application/octet-stream と {"message":"fail"} で応答していたため、Waffo は通知を再配信し続けました。確認応答するには：
Content-Type: application/jsonで応答してください。- イベントを処理した後、ボディ
{"message":"success"}で応答してください。failed/unknownの応答、200 以外のステータス、タイムアウト、パースできないボディはいずれも再試行スケジュールを発動させます。Webhook の再試行を参照してください。 - ハンドラーを冪等にしてください。再試行があるということは、同じイベントが複数回届き得るということです。