/cashin/pix/refund-partner 代收退款接口介绍

接口背景

/cashin/pix/refund-partner 提供给合作商的收款订单退款申请接口。合作商可以通过原平台订单号或原商户订单号定位原收款订单，并提交本次退款金额、退款原因等信息。

原平台订单号 origPlatOrderNo 和原商户订单号 origMerchantOrderNo 至少填写一个。退款申请本金 refundAmount 不包含手续费，币种必须与原订单币种保持一致，金额单位为元。合作商应保证商户退款订单号在同一商户范围内唯一，用于退款请求的幂等控制和后续跟踪。

退款时限：Pix 原路退款须在原交易完成后的 90 个自然日内发起，超过 90 天不允许退款。该 90 天期限仅指"Pix 原路退款"，不是所有退款及 MED 的统一期限。超过该期限，原交易不再支持通过 Pix 退款接口退回；如仍需向客户返还资金，应通过新的付款流程处理。MED 争议适用独立的监管时效及处理规则。

接口请求地址

项目	内容
请求方式	POST
请求路径	/cashin/pix/refund-partner
Content-Type	application/json
接口用途	发起收款订单退款

接口接入规范

• common接入规范

接口请求字段

字段名	位置	类型	字段长度	是否必填	说明
X-Merchant-Id	Header	string	64	是	一级商户号，从请求头读取。
X-Timestamp	Header	int	19	是	Unix 秒级请求时间戳，用于请求时效校验。
X-Nonce	Header	string	64	是	请求防重放随机字符串。
Digest	Header	string	52	是	请求体摘要，格式为 SHA-256=<Base64摘要>。
Authorization	Header	string	-	是	ES256 请求签名信息，其中 keyId 为合作商密钥版本号。
subMerchantNo	Body	string	64	是	二级商户号。
origPlatOrderNo	Body	string	64	二选一	原平台订单号；与 origMerchantOrderNo 至少填写一个。
origMerchantOrderNo	Body	string	64	二选一	原商户订单号；与 origPlatOrderNo 至少填写一个。
merchantOrderNo	Body	string	64	是	商户退款订单号；同一商户范围内应保持唯一。
refundAmount	Body	decimal	25,2	是	本次申请退还的本金金额，不包含手续费，必须大于 0；币种必须与原订单币种一致。可以多次退款，累计退款本金不能超过原订单本金。
refundReason	Body	string	128	是	退款原因。
refundReasonCategory	Body	string	16	否	退款原因分类。
notifyUrl	Body	string	255	否	合作商接收退款结果通知的地址。

请求示例

请求头示例：

POST /cashin/pix/refund-partner HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1790200000
X-Nonce: 550e8400-e29b-41d4-a716-446655440000
Digest: SHA-256=<Base64摘要>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

请求 Body 示例：

{
  "subMerchantNo": "SUB00000001",
  "origPlatOrderNo": "BAS202608160000000001",
  "origMerchantOrderNo": "CASHIN202608160001",
  "merchantOrderNo": "REFUND202608160001",
  "refundAmount": 50.00,
  "refundReason": "商户与客户协商退款",
  "refundReasonCategory": "CUSTOMER_REQUEST",
  "notifyUrl": "https://merchant.example.com/callback/refund"
}

接口响应字段

接口使用统一的 status、msg、data 响应结构。退款的最终结果应以 orderStatus、异步通知或后续查询结果为准。

字段名	类型	字段长度	是否必返	说明
status	int	4	是	响应码
msg	string	128	是	与 status 对应
data	object	不适用	否	退款响应数据；请求在验签或协议解析阶段失败时可能不返回。
data.subMerchantNo	string	64	是	二级商户号，与请求中的 subMerchantNo 一致。
data.merchantOrderNo	string	64	是	商户退款订单号，回写请求值。
data.platOrderNo	string	64	条件必返	平台退款订单号；退款订单创建成功后返回。
data.amount	decimal(25,2)	25,2	是	本次申请退还的本金金额，不包含手续费，回写请求中的 refundAmount。
data.refundAmount	decimal(25,2)	25,2	是	本次成功退还的本金金额，不包含手续费；本次退还的手续费见 data.feeRefundAmount。
data.feeRefundAmount	decimal(25,2)	25,2	是	本次退还的手续费金额；未退还手续费时为 0。
data.origPlatOrderNo	string	64	条件必返	原平台订单号。
data.origMerchantOrderNo	string	64	条件必返	原商户订单号。
data.origAmount	decimal	25,2	条件必返	原商户订单金额。
data.origTotalRefundAmount	decimal(25,2)	25,2	条件必返	原代收订单当前累计成功退还的本金金额，不包含手续费。
data.origTotalFeeRefundAmount	decimal(25,2)	25,2	条件必返	原代收订单当前累计成功退还的手续费金额，不包含退款本金。
data.e2eId	string	64	否	Pix 端到端交易 ID。
data.orderStatus	string	16	是	退款当前状态。
data.refundTime	int	19	否	退款时间，Unix 秒级时间戳。

data.orderStatus 枚举

枚举值	状态说明	是否终态
PENDING	退款处理中；	否
SUCCESS	退款成功；	是
FAILED	退款失败；	是

响应示例

以下示例为原订单首次退款成功：退还本金 50.00、手续费 0.30，累计退款本金为 50.00，累计退还的手续费为 0.30。

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "subMerchantNo": "SUB00000001",
    "merchantOrderNo": "REFUND202608160001",
    "platOrderNo": "RFD202608160000000001",
    "amount": 50.00,
    "refundAmount": 50.00,
    "feeRefundAmount": 0.30,
    "origPlatOrderNo": "BAS202608160000000001",
    "origMerchantOrderNo": "CASHIN202608160001",
    "origAmount": 100.00,
    "origTotalRefundAmount": 50.00,
    "origTotalFeeRefundAmount": 0.30,
    "e2eId": "E1234567820260816000000000000001",
    "orderStatus": "SUCCESS",
    "refundTime": 1786887025
  }
}

响应错误码

• 响应状态