返金チケットの作成 - Waffo Pancake

POST /api/actions/refund-ticket/create-ticket 認証： マーチャント API Key（サーバー間）。

リクエストボディ

フィールド	型	必須	説明
`paymentId`	string	必須	返金対象の支払い Short ID（例：`PAY_6eYCunG3IMmIgcQOnaXdoA`）
`reason`	string	必須	自由テキストの理由（customer / dashboard 表示）
`requestedAmount.amount`	string	必須	表示形式の返金額（例：`"10.50"`）、`> 0` かつ `≤ payment.amount`
`requestedAmount.currency`	string	必須	ISO 4217 コード、支払い通貨と一致する必要あり
`refundTicketMerchantExternalId`	string	任意	マーチャント業務側の返金チケット識別子（最大 128 文字）

成功レスポンス (200)

{
  "data": {
    "ticket": {
      "id": "TKT_3bVzrkD0FJjFdZNLk8Ualx",
      "status": "processing",
      "subjectId": "PAY_6eYCunG3IMmIgcQOnaXdoA",
      "refundTicketMerchantExternalId": "REF-2026-00891"
    }
  }
}

マーチャントが API Key で submit すると、チケットは自動承認され、すぐに processing へ移行します。

エラーレスポンス

リトライポリシー：4xx は一切リトライしない — リクエストを修正してから再送信。5xx は指数バックオフでリトライ（5s 開始、最大 3 回）。

ステータス	`errors[0].message`	意味	推奨処理
400	`Missing required field: <name>`	必須フィールド欠落（`paymentId`、`reason`、`requestedAmount.amount`、`requestedAmount.currency`）	ボディを修正して再送信
400	`Expected format: PAY_xxx, got "..."`	`paymentId` Short ID のデコード失敗	`paymentId` フォーマットを修正して再送信
400	`Invalid requestedAmount.amount format`	金額文字列が解析できない	表示形式（`"10.50"` など、最小単位ではない）を使用
400	`refundTicketMerchantExternalId must be at most 128 characters`	値が 128 文字を超過	128 文字以内に短縮
401	`Unauthorized`	API Key 署名が無効	認証ヘッダーを確認
404	`Payment not found`	支払いが存在しないか、ストアに属していない	`paymentId` を確認
409	`Payment status is X, must be succeeded`	元の支払いが `succeeded` 状態ではない	リトライしない — 支払いが成功していない
409	`Payment is not yet fully processed by PSP, please retry later`	PSP 確認の書き戻しが未完了	5–30 秒後にリトライ（一時的）
409	`Refund period expired (X days, max 14)`	14 日窓を超過	リトライしない — 返金不可
409	`Requested amount must be greater than 0`	金額が ≤ 0	金額を修正して再送信
409	`Requested amount exceeds payment amount`	金額が `payment.amount` を超過	金額を修正して再送信
409	`Currency mismatch: requested X, payment Y`	通貨が支払いと一致しない	支払いの通貨を使用
409	`A refund record already exists for this payment`	この支払いには既に成功済みの返金がある	リトライしない — GraphQL で既存返金を照会
409	`A refund ticket already exists for this payment`	進行中の別チケットがブロック中	既存チケット終了後に再送信を検討
500	`Internal server error`	サーバ側の予期しない障害	指数バックオフでリトライ（5s 開始、最大 3 回）

GraphQL を使用して作成したチケットと実行された返金レコードを照会します。返金チケットのビジネス番号で実行された返金をフィルタリングするには refunds(filter: { refundTicketMerchantExternalId: ... }) を使用します。

⌘I