メインコンテンツへスキップ
POST /api/actions/refund-ticket/create-ticket 認証： マーチャント API Key（サーバー間）。

​
リクエストボディ

フィールド型必須説明
paymentIdstring必須返金対象の支払い Short ID（例：PAY_6eYCunG3IMmIgcQOnaXdoA）
reasonstring必須自由テキストの理由（消費者 / dashboard 表示）
requestedAmount.amountstring必須表示形式の返金額（例："10.50"）、> 0 かつ ≤ payment.amount
requestedAmount.currencystring必須ISO 4217 コード、支払い通貨と一致する必要あり
refundTicketMerchantExternalIdstring任意マーチャント業務側の返金チケット識別子（最大 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意味推奨処理
400Missing required field: <name>必須フィールド欠落（paymentId、reason、requestedAmount.amount、requestedAmount.currency）ボディを修正して再送信
400Expected format: PAY_xxx, got "..."paymentId Short ID のデコード失敗paymentId フォーマットを修正して再送信
400Invalid requestedAmount.amount format金額文字列が解析できない表示形式（"10.50" など、最小単位ではない）を使用
400refundTicketMerchantExternalId must be at most 128 characters値が 128 文字を超過128 文字以内に短縮
401UnauthorizedAPI Key 署名が無効認証ヘッダーを確認
404Payment not found支払いが存在しないか、ストアに属していないpaymentId を確認
409Payment status is X, must be succeeded元の支払いが succeeded 状態ではないリトライしない — 支払いが成功していない
409Payment is not yet fully processed by PSP, please retry laterPSP 確認の書き戻しが未完了5–30 秒後にリトライ（一時的）
409Refund period expired (X days, max 14)14 日窓を超過リトライしない — 返金不可
409Requested amount must be greater than 0金額が ≤ 0金額を修正して再送信
409Requested amount exceeds payment amount金額が payment.amount を超過金額を修正して再送信
409Currency mismatch: requested X, payment Y通貨が支払いと一致しない支払いの通貨を使用
409A refund record already exists for this paymentこの支払いには既に成功済みの返金があるリトライしない — GraphQL で既存返金を照会
409A refund ticket already exists for this payment進行中の別チケットがブロック中既存チケット終了後に再送信を検討
500Internal server errorサーバ側の予期しない障害指数バックオフでリトライ（5s 開始、最大 3 回）
GraphQL を使用して作成したチケットと実行された返金レコードを照会します。返金チケットのビジネス番号で実行された返金をフィルタリングするには refunds(filter: { refundTicketMerchantExternalId: ... }) を使用します。