跳到主要内容

处理退款

当商家在 Shoplazza 后台提交退款请求时，退款处理流程开始。Shoplazza 调用支付应用的退款 API，支付应用同步返回退款结果。如果退款仍处于处理中，支付应用必须异步通知 Shoplazza 最终结果。

时序步骤​

退款时序图

  1. 商家在 Shoplazza 后台确认退款并提交请求。
  2. Shoplazza 接收退款请求并开始退款流程。
  3. Shoplazza 组装退款请求并调用支付应用的退款 API。
  4. 支付应用同步返回退款结果。
  5. Shoplazza 处理并展示退款结果。
  6. 必要时，支付应用异步通知 Shoplazza 最终退款结果。
  7. Shoplazza 处理退款通知并更新订单状态。

请求头​

Header说明
Shoplazza-Shop-IdShoplazza 系统中的店铺 ID。
Shoplazza-Shop-DomainShoplazza 分配的系统域名。
Shoplazza-Request-Id唯一请求 ID。
Shoplazza-Api-VersionOpen API 版本。
Shoplazza-Hmac-Sha256用于请求校验的数字签名。

请求参数​

Shoplazza 通过调用 refund session URL 将支付相关信息传给支付服务商。服务商同步返回退款结果。如果当前状态不是最终状态，服务商必须后续发送异步退款通知。

请求体以 x-www-form-urlencoded 形式发送。

json
{
  "id": "7eb3fefb-6b43-4400-b40a-a2a0531364ae",
  "app_id": "db5fc9a6-2a64-11ec-8d3d-0242ac130003",
  "account_id": "TIOnETZE",
  "payment_id": "7eb3fefb-6b43-4400-b40a-a2a0531364ae",
  "amount": "254.20",
  "currency": "CAD",
  "callback_url": "https://developer.myshoplaza.com/openapi/2021-07/payments_apps/notify_callbacks?version=1.0",
  "test": false,
  "type": "refund",
  "extra": "625598363623041156",
  "timestamp": "2021-09-01T18:32:20Z"
}
Parameter是否必填类型说明
id是string唯一退款 ID，用于幂等。
app_id是string支付应用 ID。
account_id是string支付服务商系统中的商户 ID。
payment_id是string原支付 ID。
amount是string退款金额，保留两位小数。
currency是string币种代码，例如 USD 或 CAD。
callback_url是string异步退款结果通知 URL。
test否boolean请求是否为测试模式。
type是string固定值：refund。
extra是string附加信息。
timestamp是longISO 8601 时间戳。

退款响应​

Key类型是否必填说明
refund_idstring是退款 ID，用于幂等。
statusstring是退款状态：refund_success、refund_failed 或 refund_pending。
messagestring是退款说明或失败原因。

响应示例​

json
{
  "refund_id": "db5fc9a6-2a64-11ec-8d3d-0242ac130003",
  "status": "refund_success",
  "message": "success"
}
在此页面