跳转到主要内容
POST
Create a refund
请使用属于目标组织、且为全部权限或勾选了 sales:refunds:execute 权限的 API 密钥进行认证。只有 Owner、Admin 和 Finance 角色可以授予该权限。
  • 仅在 Anyway 为你的组织开通 API 退款后可用,请联系 Anyway 支持开通。开通前,无论使用哪种密钥,对你的订单发起的退款都返回 403 REFUND_API_NOT_ENABLED。订单本身的错误(如订单不存在时的 404)会先返回。
  • 输入与控制台订单上的退款按钮相同。省略 amountCents 即退还订单剩余可退的全部金额。reason 可选:duplicate、fraudulent 或 requested_by_customer。币种始终为订单币种。
  • 请发送唯一的 Idempotency-Key 请求头(必填;1–200 个 ASCII 字符,范围 0x21 到 0x7E,不含空格)。相同密钥和相同请求体返回同一笔退款,不会重复退款。相同密钥搭配不同的订单、金额或原因返回 409。
  • 仅支持 90 天内的银行卡订单。更早的订单请联系 Anyway 支持。
  • 200 且 status 为 succeeded 表示退款已完成。202 且 status 为 pending 表示退款在等待 Anyway 审核或卡组织处理。当这笔退款使订单累计退款金额达到审核阈值或以上,或使你的组织超出每日退款限额(与控制台退款共用)时,需要审核;同一订单同一时间只能有一笔退款在等待审核。请使用相同的 Idempotency-Key 重试以获取最新状态,或等待 refund.succeeded 或 refund.failed Webhook。
  • 响应与查看退款返回的退款对象相同。通过 API 发起的退款也会显示在控制台的订单上。

授权

X-API-Key
string
header
必填

Merchant API key (format: ak_BASE64)

请求头

Idempotency-Key
string
必填

Unique creation request key: 1-200 ASCII characters in the range 0x21-0x7E (no spaces or control characters)

Required string length: 1 - 200

请求体

application/json

Order and amount

orderId
string
必填

The order to refund (ORD...). Card orders only.

amountCents
integer

Amount to refund, in the order's currency. Omit to refund everything still refundable.

reason
enum<string>

Optional reason

可用选项:
duplicate,
fraudulent,
requested_by_customer

响应

OK. The refund succeeded, or an earlier request with this Idempotency-Key is returned.

data
object
error
object
message
string
success
boolean