返金はどの識別子を持ち、誰にどれを伝えますか？
返金は最大 6 つの識別子を持ちます。3 つは貴社が生成し、3 つは Waffo が生成します。
使い分け：
- Waffo サポートとのやり取り →
acquiringRefundOrderId。元の決済に関わる質問であればacquiringOrderIdも。 - 貴社自身の帳簿の照合 →
merchantRefundOrderIdとorigPaymentRequestId。貴社のシステム内で意味を持つのは この 2 つだけです。 - 返金のリトライ →
refundRequestIdをそのまま。新しい値を使うと新しい返金が作成されます。それがこのフィールドの 趣旨です。 - 顧客とのやり取り → 上記のいずれでもありません。顧客が自身の決済履歴で目にするのは元の決済の参照番号であり、
それは元の注文の
payMethodResponse内のpayMethodRefIdとして返ります。第三者に資金を指し示す必要がある場合、 相手が認識するのはその参照番号です。 どの金額・通貨フィールドを確認すべきかを参照してください。
merchantRefundOrderId と refundRequestId はいずれも Portal → Transactions → Refunds の列として表示されるため、
API で起票した返金を貴社自身の番号で Portal から探すことができ、Portal で起票した返金を Waffo の番号で探すこともできます。
返金で顧客の銀行口座、氏名、国籍が求められるのはなぜですか？
一部の決済手段では、資金を来た経路に沿って単純に戻すことができず、返金が顧客への Payout として実行されるためです。 Payout には、決済では必要としなかった受取人の情報が必要になります。これは貴社のアカウントや個々の返金ではなく、 決済手段の属性です。 API では、これを返金リクエスト上の任意のuserInfo オブジェクトとしてモデル化し、決済手段が必要とする場合に必須になります。
値はどこから取得しますか？ 顧客からです。Waffo は顧客の銀行口座を保持しておらず、元の決済でも保持していませんでした。
だからこそこのフィールドが求められるのです。実務上は、これらの決済手段での返金はワンクリックの操作ではなく、
まず顧客に口座情報を確認する必要があるということです。Refund を押した時点で気付くのではなく、返品プロセスに
組み込んでください。
どのフィールドが不足しているかは通知されるため、推測する必要はありません。 両方の入口で同じように動作します。
- Portal では、返金ドロワーを開くとその注文に必要なフィールドが正確に求められます。銀行は固定の候補から選ぶ 検索可能なリスト、国籍は国の一覧から選びます。氏名は 60 文字、その他のテキストフィールドは 64 文字が上限で、 電話番号は決済の国の国番号に対して検証されます。任意なのはミドルネームのみです。
- API では、必須フィールドを欠いたまま送信された返金は、どのフィールドパスが不足しているかを返します。それらを 収集して再送してください。2 回目でさらに多くが求められるのは正常です。すべてを先回りして埋めるのではなく、 求められたものを提供して再送してください。
銀行口座を誤って入力して返金が失敗しました。その返金を修正できますか？
いいえ。返金記録は編集できず、失敗した返金に「修正して再送」というアクションはありません。新しいrefundRequestId で新しい返金を起票し、正しい情報を入力してください。
再送前に確認すべき 2 点：
- 返金可能な金額。 失敗した試行がすべてを解放したと仮定するのではなく、返金レスポンスまたは返金照会の
remainingRefundAmountを使用してください。これが正式な数値であり、その注文のすべての返金をすでに考慮しています。 - 情報そのもの。 誤った受取人情報で失敗した返金は、同じ情報で再び失敗します。貴社の記録からではなく、顧客に 口座を確認してください。
refundRequestId の再利用も役に立ちません。これは冪等キーなので、再送すると新しい情報での新しい試行ではなく、
元の返金が返ってきます。冪等なリトライの動作は返金 FAQで扱っています。
顧客自身が返金を開始できますか？
いいえ。 返金は貴社が Portal または返金 API を通じて開始するものであり、顧客向けの経路はありません。Waffo の チェックアウトに返金のアクションはなく、顧客がアクセスできるサブスクリプションのセルフ管理ページにもありません。 そこでサブスクリプションをキャンセルすると将来の請求が止まりますが、過去の請求が取り消されるわけではありません。 返金記録のrefundSource も同じことをフィールドの形で示しています。4 つの値は次のとおりです。
顧客を表す値はありません。顧客の経路が存在しないからです。顧客ができるのは自身の銀行に異議を申し立てることで、
これは資金も期限も異なる別の仕組みです。チャージバック FAQを参照してください。
プロダクト上の実務的な帰結：セルフサービスの返品を提供したい場合は、リクエストのフローを貴社側で構築し、承認した
時点で返金 API を呼び出してください。顧客を誘導できる Waffo の顧客向け画面を待たないでください。
すでに自分で顧客に返金しました。返金 API を呼ぶと二重に支払われますか？
はい。Waffo を通じた返金は実際の資金の移動であり、Waffo はプラットフォーム外で顧客と精算した内容（貴社自身が行った 銀行振込、ストアクレジット、店頭での現金返金）を一切把握していません。両者を照合する仕組みはないため、プラットフォーム外の 返金の後に返金を呼び出すと、顧客に 2 回目の支払いが行われます。 安全策は、Waffo が代行できるチェックではなく、返金記録そのものです。- 返金前に注文の返金履歴を確認してください。 Portal または返金照会で確認し、
remainingRefundAmountを読んでください。 貴社が起票していない返金も含めて、Waffo がすでに送金した内容が分かります。 - プラットフォーム外の精算を貴社自身のシステムに記録し、返金アクションをそれで制御してください。その情報が存在するのは そこだけです。
- 決済手段が許す場合は、Waffo 経由での返金を優先してください。まさに返金が決済と同じ記録に収まるようにするためです。
Portal から一部の金額だけ返金できますか？
はい。Portal の返金ドロワーは返金可能な全額が入力された状態で開き、金額フィールドは編集可能です。注文の通貨で、 その通貨の小数精度の範囲内で、ゼロより大きく決済金額以下の任意の金額を入力できます。理由の入力が必須であり、 返金が作成される前にダイアログで正確な金額を確認します。 同じ注文で2 回目の一部返金が可能かどうかは、Portal ではなく決済手段の問題です。一部返金を 1 回のみ許可し、 それ以上は認めない決済手段もあります。段階的な返金を計画する前に 決済手段別の返金制限を参照してください。また、Portal から返金する ステーブルコインの注文には、元のチェーン上の受取アドレスが追加で必要です。返金記録に RDR、ETHOCA、CDRN と表示されています。その注文をまだ返金できますか？
その注文は、アラートサービスが予見した異議申し立てを未然に防ぐため、すでに自動的に返金されています。したがって：
- その注文に対してこれ以上の返金はできません。 チャージバックアラートサービスが起票した失敗以外の返金が
注文に付いた時点で、それ以降のすべての返金試行は専用のエラー
A0039 Order has already been refunded by chargeback alert serviceで拒否されます。金額にかかわらずです。このチェックは自動返金が決済全額をカバーしたか どうかを見ないため、そのような注文でremainingRefundAmountがゼロより大きくても、残りを API や Portal から 返金できるわけではありません。顧客にまだ支払うべき金額があると考える場合は、サポートの案件になります。 - 自動返金が行われなかったと仮定して、Waffo の外で顧客に再度返金しないでください。 まず返金記録を読んでください。
refundSourceはそのためにあります。
A0019）で返金がブロックされます。この区別は重要です。A0039 は
すでに返金済み、A0019 は異議申し立ての進行中はロックを意味します。いずれもそのままではリトライできません。
返金 Webhook はいつ発火し、どこに送られますか？
返金が最終状態、つまり完了または失敗に達したときに発火します。中間の「返金を受理」という Webhook はないため、REFUND_IN_PROGRESS の通知は届きません。
配信先：
イベントタイプは
REFUND_NOTIFICATION で、ボディは返金照会のレスポンスと同じ構造なので、1 つのパーサーで両方に
対応できます。これは意図的です。返金照会を読める連携は Webhook も読めるため、ポーリングは 2 つ目の実装ではなく
正当なフォールバックになります。
運用上の注意が 2 点。refundNotifyUrl の上限は 256 文字で、決済の notifyUrl より短いです。また、決済の Webhook と
同じ配信ルールが適用されます。標準ポート上の到達可能な HTTPS であることと、期待される成功レスポンスのボディです。
配信のトラブルシューティングは
Webhook リトライと
Portal の Webhook ログにあります。
Webhook を待たずにポーリングで返金結果を取得できますか？
はい。/api/v1/refund/inquiry は返金の現在の状態を返し、通知 URL を設定していない場合、署名検証に失敗した場合、
あるいは単に今すぐ答えが欲しい場合の、文書化されたフォールバックです。refundStatus、失敗時の refundFailedReason、
refundCompletedAt、remainingRefundAmount、および識別子一式を返します。
決済についても同じで、Order Inquiry は結果を取得する正規の方法であり、回避策ではありません。ポーリングが解消しないのは、
Webhook を処理する必要そのものです。Webhook の経路を構築し、照会は隙間を埋めることと、サポートチームからの
「今どうなっているか」という質問に答えることに使ってください。
返金が顧客に届くまでどのくらいかかりますか？
顧客の支払い方法によって異なり、正直なところ幅があります。Waffo の担当部分、すなわち返金を最終状態に移すことはrefundStatus が報告しますが、最後の区間は顧客の銀行、カードイシュア、ウォレット事業者の手にあり、Waffo はその
到着日を約束しません。Portal のサポート画面には決済手段ごとの目安処理時間が表示されます。顧客と話すときはそれを
基準にしてください。数値は変わっても、答えの形は安定しています。
顧客対応での使い方：
- 返金が進行中と表示されている間は、返金が進んでいると伝えてください。エスカレーションすべきものはありません。
- 返金が完了と表示され、その決済手段の目安期間を過ぎても資金が届かない場合は、報告する価値があります。
acquiringRefundOrderIdを添えてください。 - 日付を約束しないでください。 特にカードの返金は、予測できる日ではなく明細サイクルに載ります。
返金では、顧客が支払った手数料や税も返りますか？
必ずしも返りません。API はこの点を明示しています。返金において、顧客が受け取る金額であるfinalDealAmount は、
顧客が当初支払ったサービス手数料や税を除外することがあり、そのため対応する注文金額より小さくなりえます。
したがって、顧客とやり取りする際には区別すべき 2 つの金額があります。
顧客には後者を伝えてください。手数料込みで顧客を元の状態に戻すのが貴社のポリシーであれば、その分は貴社自身で
価格に織り込む必要があります。注文金額の返金が自動的に手数料を戻すわけではありません。
元の決済で貴社が支払った手数料や、マーチャント負担の税がどうなるかは、返金記録ではなく精算の問題です。
返金 FAQと
手数料と税の取り扱いを参照してください。
返金理由は何文字まで書けますか？ 顧客に表示されますか？
refundReason はすべての返金で必須です。上限は起票する場所によって異なります。API は最大 256 文字を受け付け、
Portal の返金フォームは文字数カウンターとともに 128 文字でフィールドを制限します。
これは内部向けの注記です。返金記録に保持され、Portal に表示され、返金照会で返ってきます。半年後に貴社のサポートチームが
読むものです。顧客へのメッセージとしてではなく、その読み手に向けて書いてください。注文の参照番号、返品チケット番号、
簡潔な理由などです。
返金はどこで確認でき、何をエクスポートできますか？
Portal → Transactions → Refunds が一覧です。その列は識別子一式と各返金の状態をカバーします。
一覧は返金の識別子、ステータス、通貨、Refund Batch ID、作成日時でフィルターでき、エクスポートも可能です。
エクスポートはバックグラウンドタスクとして実行され、独自の期間・サイズ制限と独自のステータス一覧を持ちます。
エクスポートが成功しつつ失敗件数がゼロでない場合も含め、すべて
エクスポートセンターにあります。取引と返金のエクスポートがどの列を持つかは
決済手段の設定と制限にあります。
API で起票した返金が一覧にない場合は、失われたと結論する前に、貴社自身の
refundRequestId または
merchantRefundOrderId で検索してください。これらは列であり、返金は貴社自身の番号で見つけられます。
返金は成功と表示されているのに、顧客は資金が届いていないと言っています
同じ苦情を生む状況が 3 つあるため、次の順序で確認してください。- その決済手段の目安期間を確認してください（Portal のサポート画面に表示されます）。次の明細サイクルにまだ 達していないカードの返金は遅延ではありません。
refundAmountではなくfinalDealAmountを確認してください。 手数料が返らなかった場合、顧客は想定より 少ない金額を受け取っており、それを「届いていない」と受け取ることがあります。- 資金がどこに送られたかを確認してください。 ウォレット残高に返金される決済手段では、その背後のカードではなく ウォレットに入ります。カードの明細を見ている顧客には見えません。
acquiringRefundOrderId と日付を送ってください。
成功と報告されながら下流で失敗する返金、および ORDER_REFUND_FAILED で終わる返金は
決済手段別の返金制限で扱っています。
ステーブルコイン決済の返金には独自の必須フィールド（同じチェーン上の受取アドレス）と、ネットワーク手数料を誰が
負担するかについての独自のルールがあります。これらは
ステーブルコインの例外にあります。
返金の追跡が必要ですか？
acquiringRefundOrderId を添えて
サポートにお問い合わせください。