发起退款

请求方式和路径

POST /payin/v1/createRefund

请求头

字段名	类型	必传	描述
content-type	string	是	application/json
x-api-key	string	是	Paydify提供，跟appId相同
x-api-timestamp	string	是	时间戳，单位毫秒
x-api-signature	string	是	签名，具体参看签名算法

请求体

字段名	类型	必传	描述
mchTxnId	string(60)	是	商户侧订单ID
paymentTxnId	string(30)	是	支付订单ID
type	string	是	退款责任方： - MERCHANT: 商户负责退款（链上退款），需要提供 txnHash - PLATFORM: 平台负责退款（API/托管钱包），需要提供 refundAmount
refundAmount	string(32)	条件	退款金额（USDT） - PLATFORM 类型：必填 - MERCHANT 类型：不需要
txnHash	string(120)	条件	链上退款交易的 Hash - PLATFORM 类型：不需要 - MERCHANT 类型：必填
mchExtInfo	string(512)	否	商户扩展信息，JSON字符串
merchantId	string(64)	条件	退款归属商户 ID（子商户）。合作伙伴（Partner）凭据代发时必填；商户自有凭据可不传，默认归属凭据所属商户。最长 64 字符
merchantAppId	string(64)	条件	归属商户下的应用 ID，用于归属商户存在多个已授权应用时消歧。凭据覆盖该商户多个应用时必填；仅一个授权应用时可不传，系统自动匹配。最长 64 字符

响应头参数

字段名	类型	必传	描述
x-api-key	string	是	Paydify提供，跟appId相同
x-api-timestamp	string	是	时间戳，单位毫秒
x-api-signature	string	是	签名，具体参看签名算法

返回值

字段名	类型	描述
code	string	响应码，SYS_SUCCESS表示成功
message	string	响应消息
messageDetail	string	响应消息详情
success	boolean	是否成功
data.refundTxnId	string	Paydify侧的退款订单ID
data.paymentTxnId	string	关联的支付订单ID
data.mchTxnId	string	商户侧的退款订单ID（即请求中的 mchTxnId）
data.state	string	退款状态，枚举值参看退款状态
data.errorMsg	string	退款失败原因说明

示例

平台退款示例（Gate.io等托管模式）

// 请求体
{
  "mchTxnId": "merchant_refund_123456",
  "paymentTxnId": "P2209141130105863014",
  "type": "PLATFORM",
  "refundAmount": "100.50",
  "mchExtInfo": "{\"reason\": \"customer request\"}"
}

商户退款示例（链上退款）

// 请求体
{
  "mchTxnId": "merchant_refund_789012",
  "paymentTxnId": "P2209141130105863015",
  "type": "MERCHANT",
  "txnHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "mchExtInfo": "{\"reason\": \"customer request\"}"
}

成功返回值

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "refundTxnId": "R2209141130105863014",
    "paymentTxnId": "P2209141130105863014",
    "mchTxnId": "merchant_refund_123456",
    "state": "PENDING",
    "errorMsg": null
  },
  "success": true
}

失败返回值

{
  "code": "SYS_ERROR",
  "message": "Refund responsibility 'MERCHANT' does not match payment custody type 'CUSTODIAL'",
  "messageDetail": "Please use responsibility 'PLATFORM' for custodial payments like Gate.io",
  "data": null,
  "success": false
}

注意事项

1. type 参数必须与原支付订单的资金托管类型一致

   • 如果是托管模式支付（如 Gate.io），必须使用 type=PLATFORM（平台负责退款）
   • 如果是非托管模式支付（如 BGW、三方钱包），必须使用 type=MERCHANT（商户负责退款）

2. 参数依赖关系

   • PLATFORM 类型：必须提供 refundAmount，不需要 txnHash
   • MERCHANT 类型：必须提供 txnHash

3. 退款处理流程

   • PLATFORM 类型：调用渠道 API 进行退款
   • MERCHANT 类型：验证商户提供的链上退款交易后标记为退款成功

4. 幂等性

   • 相同的 mchTxnId 只能发起一次退款
   • 建议使用包含时间戳的唯一标识作为 mchTxnId