申请退款

POST

https://api.tipay.tianhecloud.com/api/v1/yb/trade/refund

接口描述

交易后如需要退款，商户可调用此接口将支付款退还给付款方。

使用说明

订单状态为“SUCCESS”时才能发起退款。

退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和不同的退款单号，总退款金额不能超过用户实际支付金额。

一笔退款失败后重新提交，请不要更换退款单号，请使用相同的商户退款请求号请求退款。

申请退款接口的响应参数code仅代表业务的受理情况，具体退款是否成功，需要通过申请退款结果通知或查询退款接口返回的status获取退款结果。

（1）当响应参数code=200时,说明易宝已受理该笔退款,此时需要根据status来判断退款状态；

（2）当响应参数code≠200时,说明易宝没有受理该笔退款，可根据返回的msg进行相应处理。

申请退款接口使用在求购，抢购，拍卖等这类需要频繁进行退款的业务场景时，需要向易宝支付报备进行额外配置，这类场景订单支付产生的手续费由平台承担，需确保平台账户余额充足，否则会退款失败

退款场景支持情况，申请退款接口使用在求购，抢购，拍卖等这类场景时，建议等活动结束后在进行申请分账操作
（1）订单不是分账订单，直接调用退款接口退款（支持）

（2）订单是分账订单且没有任何分账记录，直接调用退款接口退款（支持）

（3）订单是分账订单且有一部分分账记录，如果要退分出去的那部分，先调用分账归还接口，再调用退款接口（暂不支持）

（4）订单是分账订单且有一部分分账记录，如果要退尚未分出去的那部分，先调用分账接口把这部分资金分给平台，再调用退款接口（暂不支持）

（5）订单是分账订单且全部都已经分完，先调用分账归还接口，再调用退款接口（暂不支持）

请求参数

Header 参数

ti-appid

string

必需

天河链开放平台商户Id

示例值:

tichain000000

ti-timestamp

string

必需

时间戳，1970年1月1日0点0分0秒到现在的毫秒数

示例值:

1647751123703

ti-signature

string

必需

API 签名：SHA256(ParamsJson+Timestamp+AppKey)

示例值:

644dbdb0137f1f3add30eca4c9e582da5c6e45d77fea51ab76fbd10ef3442f6b

Body 参数application/json

merchantNo

string

收款商户编号

必需

示例值：10012426723

orderId

string

订单编号

必需

商户侧订单编号

refundRequestId

string

商户退款请求号

必需

请求唯一编号，示例值：refundorder987654

refundAmount

string

退款申请金额

必需

单位：元，两位小数，最低0.01，退款金额不能大于原订单金额，多次退款时，累计退款金额不能超过原订单金额示例值：88.88

description

string

退款原因

可选

示例值：用户申请退货并退款

notifyUrl

string

退款结果回调url

可选

接收退款结果通知地址，不传则不通知回调参数请参考：退款结果通知参数示例

示例

{
    "merchantNo": "string",
    "orderId": "string",
    "refundRequestId": "string",
    "refundAmount": "string",
    "description": "string",
    "notifyUrl": "string"
}

示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api.tipay.tianhecloud.com/api/v1/yb/trade/refund' \
--header 'ti-appid: tichain000000' \
--header 'ti-timestamp: 1647751123703' \
--header 'ti-signature: 644dbdb0137f1f3add30eca4c9e582da5c6e45d77fea51ab76fbd10ef3442f6b' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchantNo": "string",
    "orderId": "string",
    "refundRequestId": "string",
    "refundAmount": "string",
    "description": "string",
    "notifyUrl": "string"
}'

返回响应

🟢200成功

application/json

Body

code

integer

必需

code≠200时,说明易宝没有受理该笔退款

success

boolean

必需

success≠true时,说明易宝没有受理该笔退款

data

object

必需

merchantNo

string

商户编号

必需

示例值：10012426723

orderId

string

订单编号

必需

示例值：order123456789

refundRequestId

string

商户退款请求号

必需

示例值：refundorder987654

uniqueRefundNo

string

易宝退款订单号

必需

商户退款请求对应在易宝的退款单号示例值：10022022030600000003302144723

status

string

状态

必需

退款订单状态 PROCESSING：退款处理中 SUCCESS：退款成功 FAILED：退款失败

refundAmount

string

退款申请金额

必需

单位：元，两位小数，最低0.01，退款金额不能大于原订单金额，多次退款时，累计退款金额不能超过原订单金额示例值：88.88

refundRequestDate

string

退款受理时间

必需

示例值：2021-01-01 00:00:00

refundAccountDetail

string

退款资金来源信息

必需

debitAmount：扣账金额 accountType：扣账资金来源扣账资金来源枚举值： FUND_ACCOUNT：资金账户余额 DIVIDE_ACCOUNT：分账账户余额 SETTLE_ACCOUNT：待结算账户余额示例值：[{"accountType":"FUND_ACCOUNT","debitAmount":6.00}]

msg

string

必需

示例

{
    "code": 200,
    "success": true,
    "data": {
        "code": "OPR00000",
        "message": "成功",
        "merchantNo": "1008xxxxxxx",
        "orderId": "bda4e84ef8ee427b830d869d7a6bfd71",
        "refundRequestId": "1b118148eaf54b09a213adcb332d7a19",
        "uniqueRefundNo": "1002202301300000005245434665",
        "status": "PROCESSING",
        "refundAmount": "0.01",
        "refundRequestDate": "2023-01-30 17:08:14",
        "refundAccountDetail": "[{\"accountType\":\"SETTLE_ACCOUNT\",\"debitAmount\":0.01}]"
    },
    "msg": "操作成功"
}

🟢200退款结果通知

分账结果查询

退款查询

申请退款

接口描述#

使用说明#

请求参数

示例代码

返回响应

接口描述

使用说明