退款 API

Ask AI

为已完成的交易发起退款并查询其状态。

---

发起退款 (Initiate Refund)

接口地址 (Endpoint): POST /v2/refund
Content-Type: application/json

退款可以是 全额 (full) 或 部分 (partial)（取决于各支付渠道的限制 —— 某些渠道仅支持全额退款）。退款可能会立即自动处理，也可能会保留待人工审批，具体取决于商户配置。

每笔退款的最大可退金额为：paidAmount 减去该交易已退款的总额。

请求 (Request)

字段	类型	是否必填	描述
transactionId	String (ULID)	M	来自 IPN 或交易查询的 transactionId。例如：01jza90dy6w82dfrrqvadn5vs4
amount	Float	M	退款金额。最小值：0.10。最大值：剩余可退款金额。例如：50.00
reason	String(max:1000)	O	退款原因的简短描述。例如：客户要求
signature	String(max:750)	M	RSA-MD5 签名。请参阅 签名

某些渠道（PayAgency, SmartPay, ClisaPay, FinvyPay, WPay）仅支持全额退款。

响应 (Response)

所有响应均已包装：

字段	类型	描述
status	String	success 或 error
message	String	人类可读的消息
data	JSON	退款详情。请参阅下方的 data 对象

data 对象:

字段	类型	描述
refundId	String (ULID)	GLODIPAY 退款 ID
refundNumber	String	GLODIPAY 人类可读的退款编号

立即自动处理:

{
  "status": "success",
  "message": null,
  "data": {
    "refundId": "01jzabk09xc4pbgwe8hyg4cwbf",
    "refundNumber": "2507-1751420414"
  }
}

等待人工审批:

{
  "status": "success",
  "message": "Refund created and waiting for approval.",
  "data": {
    "refundId": "01jzabk09xc4pbgwe8hyg4cwbf",
    "refundNumber": "2507-1751420414"
  }
}

验证错误 (HTTP 422):

{
  "status": "error",
  "message": "Invalid request data.",
  "errors": [
    {
      "field": "amount",
      "message": ["金额必须在 0.1 到 100 之间。"]
    }
  ]
}

---

查询退款状态 (Query Refund Status)

接口地址 (Endpoint): POST /v2/refund/query
Content-Type: application/json

请求 (Request)

字段	类型	是否必填	描述
refundId	String (ULID)	M	GLODIPAY 退款 ID（来自退款 API 响应或退款 IPN）。例如：01jzabk09xc4pbgwe8hyg4cwbf
signature	String(max:750)	M	RSA-MD5 签名。请参阅 签名

响应 (Response)

字段	类型	描述
status	String	success
message	String	人类可读的消息
data	JSON	退款详情对象

data 对象字段:

字段	类型	描述
transactionId	String	GLODIPAY 原始交易 ID
ref	String	商户的 orderRef
refundId	String	GLODIPAY 退款 ID
currency	String	ISO 4217 货币代码
refundAmount	Float	退款金额
status	String	退款状态。请参阅 状态码
statusCode	Number	数字状态码。请参阅 状态码
metadata	JSON	原始会话中的键值对
reason	String	退款原因
message	String	人类可读的状态消息
originalRefundCreatedAt	ISO 8601 datetime	支付渠道侧的退款创建时间
refundCreatedAt	ISO 8601 datetime	GLODIPAY 系统中的退款创建时间
transactionCreatedAt	ISO 8601 datetime	原始交易创建时间
signature	String	RSA-MD5 签名 —— 使用 GLODIPAY 公钥验证

示例:

{
  "status": "success",
  "message": "",
  "data": {
    "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
    "ref": "ORDER-001",
    "refundId": "01jzabk09xc4pbgwe8hyg4cwbf",
    "currency": "USD",
    "refundAmount": 50.00,
    "status": "refund_successful",
    "statusCode": 11,
    "metadata": { "orderId": "12345" },
    "reason": "客户要求",
    "message": null,
    "originalRefundCreatedAt": "2026-04-14T11:00:00+00:00",
    "refundCreatedAt": "2026-04-14T11:00:01+00:00",
    "transactionCreatedAt": "2026-04-14T10:00:00+00:00",
    "signature": "base64-encoded-rsa-signature"
  }
}

---

退款 IPN 通知 (Refund IPN Notification)

当退款状态发生变化时，GLODIPAY 会向原始交易的 notificationUrl 发送 HTTP POST 请求。

方法: POST
Content-Type: application/json

重试策略: 如果您的服务器在 30 秒 内未返回 {"returnCode":"100"}，GLODIPAY 将重试发送。

Payload

字段	类型	是否必填	描述
transactionId	String	M	GLODIPAY 原始交易 ID
ref	String	M	商户的 orderRef
refundId	String	M	GLODIPAY 退款 ID
currency	String	M	ISO 4217 货币代码
refundAmount	Float	M	退款金额
status	String	M	退款状态。请参阅 状态码
statusCode	Number	M	数字状态码
metadata	JSON	O	原始会话中的键值对
reason	String	O	退款原因
message	String	O	人类可读的状态消息
originalRefundCreatedAt	ISO 8601 datetime	M	支付渠道侧的退款创建时间
refundCreatedAt	ISO 8601 datetime	M	GLODIPAY 系统中的退款创建时间
transactionCreatedAt	ISO 8601 datetime	M	原始交易创建时间
signature	String	M	RSA-MD5 签名 —— 使用 GLODIPAY 公钥验证

IPN Payload 示例:

{
  "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
  "ref": "ORDER-001",
  "refundId": "01jzabk09xc4pbgwe8hyg4cwbf",
  "currency": "USD",
  "refundAmount": 50.00,
  "status": "refund_successful",
  "statusCode": 11,
  "metadata": { "orderId": "12345" },
  "reason": "客户要求",
  "message": null,
  "originalRefundCreatedAt": "2026-04-14T11:00:00+00:00",
  "refundCreatedAt": "2026-04-14T11:00:01+00:00",
  "transactionCreatedAt": "2026-04-14T10:00:00+00:00",
  "signature": "base64-encoded-rsa-signature"
}

确认 (Acknowledgement)

您的服务器必须在 30 秒 内响应：

{
  "returnCode": "100",
  "description": "Received"
}

字段	类型	是否必填	描述
returnCode	String	M	必须为 "100" 以确认收到
description	String(max:1500)	O	可选描述

---

来源

此页面派生自 GLODIPAY_Refund_API_Specification_v2。