创建退款工单 - Waffo Pancake

POST /v1/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 提交时，工单自动批准，直接进入 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	`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`	已有 in-flight 工单阻塞	等待已有工单终结后再视情况重发
409	`Insufficient available balance for refund: requested X, available Y (CCY)`	原支付已结算，退款金额超过可提款金额	改退较小金额，或在可提款金额足够后重发
409	`Store owner merchant not found`	原支付已结算，但无法为你的账号确定店铺 owner 的余额	不要重试 — 请店铺 owner 发起退款
503	`Balance check temporarily unavailable, please retry later`	暂时无法校验余额；未创建工单	指数退避重试（起步 5s，最多 3 次）
500	`Internal server error`	服务端意外失败	指数退避重试（起步 5s，最多 3 次）

使用 GraphQL 查询创建的工单和执行的退款记录。按工单业务号过滤执行的退款使用 refunds(filter: { refundTicketMerchantExternalId: ... })。

⌘I