退款接口

## 统一退款
商户业务系统通过统一退款接口发起退款请求，支付网关会根据商户发起的支付订单号，找到对应到支付通道发起退款。
两周内可发起退款。
>接口说明

请求URL：https://pay.trust-pay.cn/api/refund/refundOrder

请求方式：`POST`

请求类型：`application/json` 或 `application/x-www-form-urlencoded`
>请求参数

| 字段名    | 变量名          | 必填 | 类型          | 示例值                                | 描述                             |
|--------|--------------|----|-------------|------------------------------------|--------------------------------|
| 商户号    | mchNo        | 是  | String(30)  | M1621873433953                     | 商户号                            |
| 应用ID   | appId        | 是  | String(24)  | 60cc09bce4b0f1c0b83761c9           | 应用ID                           |
| 支付订单号  | payOrderId   | 是  | String(30)  | P20160427210604000490              | 支付中心生成的订单号，与mchOrderNo二者传一即可   |
| 商户订单号  | mchOrderNo   | 是  | String(30)  | 20160427210604000490               | 商户生成的支付订单号，与payOrderId二者传一即可   |
| 商户退款单号 | mchRefundNo  | 是  | String(30)  | M27210632100491                    | 商户生成的退款单号                      |
| 退款金额   | refundAmount | 是  | int         | 100                                | 退款金额,单位分                       |
| 货币代码   | currency     | 是  | String(3)   | cny                                | 三位货币代码,人民币:cny                 |
| 退款原因   | refundReason | 是  | String(64)  | 用户退货                               | 退款原因                           |
| 客户端IP  | clientIp     | 否  | String(32)  | 210.73.10.148                      | 客户端IPV4地址                      |
| 异步通知地址 | notifyUrl    | 否  | String(128) | https://www.baidu.com/notify.htm | 退款完成后回调该URL,只有传了该值才会发起回调       |
| 渠道参数   | channelExtra | 否  | String(256  | {“auth_code”, “13920933111042”}    | 特定渠道发起的额外参数,json格式字符串.详见渠道参数说明 |
| 扩展参数   | extraParam   | 否  | String(512) | 134586944573118714                 | 商户扩展参数,回调时会原样返回                |
| 请求时间   | reqTime      | 是  | long        | 1622016572190                      | 请求接口时间,13位时间戳                  |
| 接口版本   | version      | 是  | String(3)   | 1.0                                | 接口版本号，固定：1.0                   |
| 签名     | sign         | 是  | String(32)  | xxxxxx   | 签名值，详见签名算法                     |
| 签名类型   | signType     | 是  | String(32)  | RSA2                                | 签名类型，目前只支持RSA2方式                |

`请求示例数据`
```json
{
    "mchNo": "M1715090182",
    "appId": "664970095f763b7c914394e0",
    "payOrderId": "P1798967370861481986",
    "mchRefundNo": "M27210632100496",
    "refundAmount": 10,
    "currency": "cny",
    "refundReason": "接口调试",
    "clientIp": "117.147.104.130",
    "channelExtra": {
        "buyerUserId": "2088612334700675"
    },
    "notifyUrl": "https://merchant.trust-pay.cn/api/anon/paytestNotify/payOrder",
    "reqTime": "1718031552546",
    "version": "1.0",
    "signType": "RAS2",
    "sign": "qcahbGGOovDRr2XaJIDgKFVqCC/6/CezOnkd3m7h8GoknGzwnZY580YWCFn1nktSx/nwwxEaMqMuVLwKzr7EXza4Errqci2hD6/5K1WUYLHQyUELS7zlqEib015eckWHZYXLHd9/HS7QEpCz4vg4wsrp4CNhhx5doNMHXL4g8FyuvtwqO/eyW/hwwwjOsyfsai4CXU7DIrkE/fZ8i7JRf6aY8uhBckcfHHHqbgpqOSJphYqxf2LEjlDEFKyIa3ezxnpsQziGOFIou9POB2T5aJvINaDvarmZOfO/SRknjQIAjrbnroe667tD60N5vWATWZ6MUsFpJgbR6uUEIihxrw=="
}
```
>返回参数

| 字段名  | 变量名  | 必填 | 类型          | 示例值                              | 描述                      |
|------|------|----|-------------|----------------------------------|-------------------------|
| 返回状态 | code | 是  | int         | 0                                | 0-处理成功，其他-处理有误，详见错误码    |
| 返回信息 | msg  | 否  | String(128) | 签名失败                             | 具体错误原因，例如：签名失败、参数格式校验错误 |
| 签名信息 | sign | 否  | String(32)  | CCD9083A6DAD9A2DA9F668C3D4517A84 | 对data内数据签名,如data为空则不返回  |
| 返回数据 | data | 否  | String(512) | {}                               | 返回下单数据,json格式数据         |

`data数据格式`

| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|--------|---------------|----|------------|------------------------|-------------|
| 退款订单号 | refundOrderId | 是 | String(30) | R202106181708358940000 | 返回退款订单号 |
| 商户退款单号 | mchRefundNo | 是 | String(30) | mho1624007315478 | 返回商户传入的退款单号 |
| 退款状态 | state | 是 | int | 2 | 退款状态 0-订单生成 1-退款中 2-退款成功 3-退款失败 4-退款关闭 |
| 渠道退款单号 | channelOrderNo | 否 | String | 20160427210604000490 | 对应渠道的退款单号 |
| 渠道错误码 | errCode | 否 | String | ACQ.PAYMENT_AUTH_CODE_INVALID | 上游渠道返回的错误码 |
| 渠道错误描述 | errMsg | 否 | String | Business Failed 失败 | 上游渠道返回的错误描述 |
>返回示例数据

```json
{
    "code": 0,
    "data": {
        "mchRefundNo": "M27210632100496",
        "payAmount": 10,
        "refundAmount": 10,
        "refundOrderId": "R1800180958355103746",
        "state": 2
    },
    "msg": "SUCCESS",
    "sign": "KS/A6XPOEUQTjGV98MwiKN7Ho7l2cPq5aClgBTN1lRRPOZ9ZPgO9WN+FHpbwmlfhhcbAM3WE1tHQRyGQT1pgKRH/h2bI2hvo04eYq3NQR3wr8FHe3y0pl3Sq0S+yTa2lMUMawH9MBt84rPDQ5AH+gFBRmVWxpTg6dUZ4vESXQMqbOYnhjrNNEpF06TTHlhYekWJdoEBoygwvxdKm95/0B9NXgiLcOPQh5OUqkblFn8Vpuf2vCpkOYM0MmogGTSWdO6RVUlXdCMJxcFeXf+ltS+tGXaanSMvA46CYoGQygMPHkZYnksKM79c3itQG0pbBaVVIWAC0TEcEbsevm/SlQw=="
}
```

## 查询订单
商户通过该接口查询退款订单，支付网关会返回订单最新的数据

请求URL：https://pay.trust-pay.cn/api/refund/query

请求方式：`POST`

请求类型：`application/json` 或 `application/x-www-form-urlencoded`
>请求参数

| 字段名    | 变量名           | 必填 | 类型         | 示例值                              | 描述                             |
|--------|---------------|----|------------|----------------------------------|--------------------------------|
| 商户号    | mchNo         | 是  | String(30) | M1621873433953                   | 商户号                            |
| 应用ID   | appId         | 是  | String(24) | 60cc09bce4b0f1c0b83761c9         | 应用ID                           |
| 退款订单号  | refundOrderId | 是  | String(30) | R20160427210604000490            | 支付中心生成的退款单号，与mchRefundNo二者传一即可 |
| 商户退款单号 | mchRefundNo   | 是  | String(30) | 20160427210604000490             | 商户生成的退款单号，与refundOrderId二者传一即可 |
| 请求时间   | reqTime       | 是  | long       | 1622016572190                    | 请求接口时间,13位时间戳                  |
| 接口版本   | version       | 是  | String(3)  | 1.0                              | 接口版本号，固定：1.0                   |
| 签名     | sign          | 是  | String(32) | xxxx | 签名值，详见签名算法                     |
| 签名类型   | signType      | 是  | String(32) | RSA2                              | 签名类型，目前只支持RSA2方式                |

>请求示例数据
```json
{
    "mchNo": "M1715090182",
    "appId": "664970095f763b7c914394e0",
    "mchRefundNo": "M27210632100496",
    "reqTime": "1718031945631",
    "version": "1.0",
    "signType": "RAS2",
    "sign": "Q+m+gySwdxR3pfnYxSwcn9RevKXLVb1+kFox4fOxNCZtmHAwmAg80FCDugIn31WgM+RkS8bzm3r5TxLmaY7pi2B1wglPV30+Wus4WO7G7t+P2EQHA2BazeNH1GYDpZsX57yYTT9Zpwp/ZL1t+hrzlkJgU4ZWqIV/VP+KA8L/zSKGdJpXyyI+N/XIygfSx98etV763xo/MkuVt1uuRS+PoAYC2VE1K0LWYycef4VN4D7MHDFvq5mlrFec4T1iioMPRLh5FK5Rfcje0I+y5Yn53Du/pUbNzzn4PviMuXvHqAJlGotfF2nQHbzdRese/7PSc7in2ubDm4Zf0W44rZJ06Q=="
}
```

| 字段名  | 变量名  | 必填 | 类型          | 示例值                              | 描述                      |
|------|------|----|-------------|----------------------------------|-------------------------|
| 返回状态 | code | 是  | int         | 0                                | 0-处理成功，其他-处理有误，详见错误码    |
| 返回信息 | msg  | 否  | String(128) | 签名失败                             | 具体错误原因，例如：签名失败、参数格式校验错误 |
| 签名信息 | sign | 否  | String(32)  | xxxxxx | 对data内数据签名,如data为空则不返回  |
| 返回数据 | data | 否  | String(512) | {}                               | 返回下单数据,json格式数据         |

`data数据格式`

| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|--------|---------------|----|------------|--------------------------|----------------|
| 退款订单号 | refundOrderId | 是 | String(30) | R20160427210604000490 | 支付中心生成的退款单号 |
| 支付订单号 | payOrderId | 是 | String(30) | P12021022311124442600 | 返回支付系统订单号 |
| 商户号 | mchNo | 是 | String(30) | M1621873433953 | 商户号 |
| 应用ID | appId | 是 | String(24) | 60cc09bce4b0f1c0b83761c9 | 应用ID |
| 商户退款单号 | mchRefundNo | 是 | String(30) | 20160427210604000490 | 商户生成的退款单号 |
| 支付金额 | payAmount | 是 | int | 100 | 支付金额,单位分 |
| 退款金额 | refundAmount | 是 | int | 100 | 退款金额,单位分 |
| 货币代码 | currency | 是 | String(3) | cny | 三位货币代码,人民币:cny |
| 退款状态 | state | 是 | int | 2 | 退款状态 0-订单生成 1-退款中 2-退款成功 3-退款失败 4-退款关闭 |
| 渠道订单号 | channelOrderNo | 否 | String | 20160427210604000490 | 对应渠道的订单号 |
| 渠道错误码 | errCode | 否 | String | 1002 | 渠道返回错误码 |
| 渠道错误描述 | errMsg | 否 | String | 134586944573118714 | 渠道返回错误描述 |
| 扩展参数 | extraParam | 否 | String(512) | 134586944573118714 | 商户扩展参数,回调时会原样返回 |
| 创建时间 | createdAt | 是 | long | 1622016572190 | 订单创建时间,13位时间戳 |
| 成功时间 | successTime | 否 | long | 1622016572190 | 订单支付成功时间,13位时间戳 |

`返回示例数据`

```json
{
    "code": 0,
    "data": {
        "appId": "664970095f763b7c914394e0",
        "createdAt": 1718031560873,
        "currency": "cny",
        "mchNo": "M1715090182",
        "mchRefundNo": "M27210632100496",
        "payAmount": 10,
        "payOrderId": "P1798967370861481986",
        "refundAmount": 10,
        "refundOrderId": "R1800180958355103746",
        "state": 2,
        "successTime": 1718031564000
    },
    "msg": "SUCCESS",
    "sign": "cLTrMTfpo25H8C6bewJQRdJ+BbSV3IRazF70KvVyEY60SMOF49pQ7AV9KTOnNKvy4TgRQuu92PtAGmY4CosDZPjM0Vn0+or8Qk7IMGNmRkbyQ0m5Xy3Iuv9s2BhKxuU3/lpOoy/S8Xn8jtkwP0GkrqWLAvov6NLQUiPn4FUX+ZdBvd3T55p1pds64lDeZzx2e9s0MK6rM0f/g7QYucc85VrtQqoS2jGo5ANKqNxKsAFkmsTKRAa3qwgYsqUO8JJZhe04v7T+A4ZJ0gzjM57mQyysTxAcuxyDBXdKsH3WqBPyTUxlvvgc6MO4F5/OKcT36sj/yYhheWPHqKj5/vNzsw=="
}
```

## 退款通知
当退款完成时(成功或失败)，支付网关会向商户系统发起回调通知。如果商户系统没有正确返回，支付网关会延迟再次通知。
>接口说明

请求URL：该链接是通过统一退款接口提交的参数notifyUrl设置，如果无法访问链接，商户系统将无法接收到支付中心的通知。

请求方式：`POST`

请求类型：`application/json` 或 `application/x-www-form-urlencoded`
>通知参数

| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|--------|---------------|----|------------|--------------------------|----------------|
| 退款订单号 | refundOrderId | 是 | String(30) | R20160427210604000490 | 支付中心生成的退款单号 |
| 支付订单号 | payOrderId | 是 | String(30) | P12021022311124442600 | 返回支付系统订单号 |
| 商户号 | mchNo | 是 | String(30) | M1621873433953 | 商户号 |
| 应用ID | appId | 是 | String(24) | 60cc09bce4b0f1c0b83761c9 | 应用ID |
| 商户退款单号 | mchRefundNo | 是 | String(30) | 20160427210604000490 | 商户生成的退款单号 |
| 支付金额 | payAmount | 是 | int | 100 | 支付金额,单位分 |
| 退款金额 | refundAmount | 是 | int | 100 | 退款金额,单位分 |
| 货币代码 | currency | 是 | String(3) | cny | 三位货币代码,人民币:cny |
| 退款状态 | state | 是 | int | 2 | 退款状态 0-订单生成 1-退款中 2-退款成功 3-退款失败 4-退款关闭 |
| 渠道订单号 | channelOrderNo | 否 | String | 20160427210604000490 | 对应渠道的订单号 |
| 渠道错误码 | errCode | 否 | String | 1002 | 渠道返回错误码 |
| 渠道错误描述 | errMsg | 否 | String | 134586944573118714 | 渠道返回错误描述 |
| 扩展参数 | extraParam | 否 | String(512) | 134586944573118714 | 商户扩展参数,回调时会原样返回 |
| 创建时间 | createdAt | 是 | long | 1622016572190 | 订单创建时间,13位时间戳 |
| 成功时间 | successTime | 否 | long | 1622016572190 | 订单支付成功时间,13位时间戳 |
| 通知请求时间 | reqTime | 是 | String(30) | 1622016572190 | 通知请求时间，,13位时间戳 |
| 签名 | sign | 是 | String(32) | xxxxxxxxx | 签名值，详见签名算法 |

> 返回结果

业务系统处理后同步返回给支付中心，返回字符串 success 则表示成功，返回非success则表示处理失败，支付中心会再次通知业务系统。（通知频率为0/30/60/90/120/150,单位：秒）
`注意：返回的字符串必须是小写，且前后不能有空格和换行符。`

`通知示例数据`

```json
{
    "appId": "60cc09bce4b0f1c0b83761c9",
    "channelOrderNo": "2021061822001423031419593035",
    "createdAt": 1623985552769,
    "currency": "cny",
    "extParam": "",
    "mchNo": "M1623984572",
    "mchRefundNo": "mho1623985552430",
    "payAmount": 58,
    "payOrderId": "P202106181104177050002",
    "refundAmount": 4,
    "refundOrderId": "P202106181105527690009",
    "state": 2,
    "successTime": 1623985554000
}
```