发起退款
请求方式和路径
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字符串 |
响应头参数
| 字段名 | 类型 | 必传 | 描述 |
|---|---|---|---|
| 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.state | string | 退款状态，枚举值参看退款状态 |
| data.errorMsg | string | 退款失败原因说明 |
示例
平台退款示例（Gate.io等托管模式）
json
// 请求体
{
"mchTxnId": "merchant_refund_123456",
"paymentTxnId": "P2209141130105863014",
"type": "PLATFORM",
"refundAmount": "100.50",
"mchExtInfo": "{\"reason\": \"customer request\"}"
}// 请求体
{
"mchTxnId": "merchant_refund_123456",
"paymentTxnId": "P2209141130105863014",
"type": "PLATFORM",
"refundAmount": "100.50",
"mchExtInfo": "{\"reason\": \"customer request\"}"
}商户退款示例（链上退款）
json
// 请求体
{
"mchTxnId": "merchant_refund_789012",
"paymentTxnId": "P2209141130105863015",
"type": "MERCHANT",
"txnHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
"mchExtInfo": "{\"reason\": \"customer request\"}"
}// 请求体
{
"mchTxnId": "merchant_refund_789012",
"paymentTxnId": "P2209141130105863015",
"type": "MERCHANT",
"txnHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
"mchExtInfo": "{\"reason\": \"customer request\"}"
}成功返回值
json
{
"code": "SYS_SUCCESS",
"message": null,
"messageDetail": null,
"data": {
"refundTxnId": "R2209141130105863014",
"paymentTxnId": "P2209141130105863014",
"state": "pending",
"errorMsg": null
},
"success": true
}{
"code": "SYS_SUCCESS",
"message": null,
"messageDetail": null,
"data": {
"refundTxnId": "R2209141130105863014",
"paymentTxnId": "P2209141130105863014",
"state": "pending",
"errorMsg": null
},
"success": true
}失败返回值
json
{
"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
}{
"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
}注意事项
type 参数必须与原支付订单的资金托管类型一致
- 如果是托管模式支付（如 Gate.io），必须使用
type=PLATFORM（平台负责退款） - 如果是非托管模式支付（如 BGW、三方钱包），必须使用
type=MERCHANT（商户负责退款）
- 如果是托管模式支付（如 Gate.io），必须使用
参数依赖关系
PLATFORM类型：必须提供refundAmount，不需要txnHashMERCHANT类型：必须提供txnHash
退款处理流程
PLATFORM类型：调用渠道 API 进行退款MERCHANT类型：验证商户提供的链上退款交易后标记为退款成功
幂等性
- 相同的
mchTxnId只能发起一次退款 - 建议使用包含时间戳的唯一标识作为
mchTxnId
- 相同的