メインコンテンツへスキップ
返金エンドポイントにより、マーチャントは成功済みの支払いに対して返金を発行できます。返金は 返金チケット（リクエスト）と 返金レコード（PSP 確認後に書き込まれる実行結果）の 2 つのモデルで構成されます。

​
ビジネスルール

  • 返金は元の支払い成功から 14 日以内 にリクエストする必要があります
  • 返金額は 部分返金（> 0 かつ ≤ payment.amount）が可能ですが、支払いと同じ通貨を使用する必要があります
  • 元の支払いが PSP によって完全に確定済みである必要があります — payment webhook 到着直後の返金呼び出しは一時的に失敗することがあります。数秒後にリトライしてください
  • pending または succeeded の返金がすでに存在する支払いに対しては別の返金チケットを作成できません
  • マーチャントがサーバーサイドの API Key で返金を送信すると、チケットは自動承認され直接 processing に遷移します — 手動レビューはありません

​
返金チケットステータス値

ステータスマーチャント視点の意味
pendingWaffo レビュー待ち（buyer が自主発起した場合のみ表示）
approved承認済み、まもなく PSP へディスパッチ
rejected拒否 — GraphQL で rejectReason を確認
processingPSP へディスパッチ済み、上流完了待ち
succeeded消費者へ資金返還済み
failedPSP が失敗を返した — 再レビュー後に再提出可能
マーチャント発起の返金は pending と approved をスキップし、作成直後に processing として表示されます。

​
ビジネス側識別子 — ビジネスレコードを紐付ける

2 つの作成エンドポイントで、それぞれビジネス側識別子（最大 128 文字）をオプションで付加できます。同一ペイロード上で両者が曖昧なく共存できるよう、対外的にはフラットなキー名を採用しています:
作成エンドポイントリクエストボディフィールド永続化先
checkout/create-sessionorderMerchantExternalIdorders.merchant_external_id（初回支払いとサブスク更新が同じ値を継承）
refund-ticket/create-ticketrefundTicketMerchantExternalIdrefund_tickets.merchant_external_id（PSP 成功後、refund レコードへ継承）
エンドツーエンドの伝播（リクエストボディ、webhook ペイロード、GraphQL 型の 3 箇所で同じフラットな双 key 名を使用）： 
checkout/create-session         (リクエスト: orderMerchantExternalId)
                                    │
                                    ├──► OnetimeOrder / SubscriptionOrder . orderMerchantExternalId
                                    ├──► Payment                          . orderMerchantExternalId   (初回 + サブスク更新)
                                    │
refund-ticket/create-ticket     (リクエスト: refundTicketMerchantExternalId)
                                    │
                                    ├──► RefundTicket                     . refundTicketMerchantExternalId
                                    │
                                    └──► Refund は両方を保持:
                                         • orderMerchantExternalId           (元の注文から継承)
                                         • refundTicketMerchantExternalId    (元の返金チケットから継承)
これらの識別子は冪等性キーではありません — Waffo は一意性を強制しません。同じ reference を複数のレコードに付加可能で、一意性の確保はあなたの責任です。 リクエストボディ、webhook ペイロード、GraphQL の 3 箇所で同じフィールド名を使用するため、checkout / refund-ticket 作成時に書き込んだ値をそのままの名前で読み戻せます。 これらの識別子で Payments、Refunds、Refund Tickets を GraphQL からクエリできます — GraphQL Orders & Payments ガイドを参照。

​
エンドポイント

返金チケットの作成

成功した支払いの返金をリクエスト。全額・部分返金に対応。

返金チケットの再送信

拒否または失敗した返金チケットを修正して再送信。
GraphQL を使用して返金チケットと実行された返金レコードを照会します。Refund では 2 つのビジネス番号をフラットフィールドで公開しています：refund.orderMerchantExternalId と refund.refundTicketMerchantExternalId（webhook ペイロードと同名）。実行された返金を返金チケットのビジネス番号でフィルタリングするには refunds(filter: { refundTicketMerchantExternalId: ... }) を使用します。