跳转到主要内容
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 提交时，工单自动批准，直接进入 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已有 in-flight 工单阻塞等待已有工单终结后再视情况重发
500Internal server error服务端意外失败指数退避重试（起步 5s，最多 3 次）
使用 GraphQL 查询创建的工单和执行的退款记录。按工单业务号过滤执行的退款使用 refunds(filter: { refundTicketMerchantExternalId: ... })。