OpenAPI-退款接口（测试）

请求参数

Header 参数

lk-appid

string

可选

示例值:

240479585243137

lk-time

string

可选

示例值:

2025-04-08 16:29:13

lk-nonce

string

可选

示例值:

9f96ac1ff4fa4595862f5709abce5eff

lk-sign

string

可选

示例值:

a37e073f77cde8428da6a9bf7750fac9

Body 参数application/json

appId

string

应用Id

必需

业务系统的应用Id

tenantId

string

租客Id

必需

租客Id

channelPayOrderNo

string

渠道支付订单号

必需

支付网关与支付渠道之间的唯一订单号，与mchOrderNo二者传一即可

mchOrderNo

string

商户订单号

必需

业务系统这一笔支付记录的唯一编号，与channelPayOrderNo二者传一即可

mchRefundNo

string

商户退款单号

必需

业务系统这一笔退款记录的唯一编号

refundMode

string

退款模式

必需

退款模式，整单退款-ENTIRE_REFUND；明细退款-ITEMIZED_REFUND

businessId

string

业务系统费用明细Id

可选

当退款模式为ITEMIZED_REFUND不能为空，

refundAmount

string

退款金额

必需

单位是分

refundReason

string

退款原因

必需

退款原因

notifyUrl

string

异步通知地址

可选

退款完成后回调该URL,只有传了该值才会发起回调

channelExtra

string

支付渠道参数

可选

特定渠道发起的额外参数,json格式字符串。（工行聚合支付没有）
当 payChannelCode=AUTO_BAR 或 payChannelCode=ALI_BAR 或 payChannelCode=WX_BAR 或 payChannelCode=YSF_BAR 时，payChannelExtra必须传auth_code，为用户的付款码值，payChannelExtra示例数据如：{"auth_code": "13920933111042"}

当 payChannelCode=ALI_JSAPI 时，payChannelExtra必须传buyerUserId，为支付宝用户ID，payChannelExtra示例数据如：{"buyerUserId": "2088702585070844"}

当 payChannelCode=WX_JSAPI 或 payChannelCode=WX_LITE 时，payChannelExtra必须传openid，payChannelExtra示例数据如：{"openid": "o6BcIwvSiRpfS8e_UyfQNrYuk2LI"}

当 payChannelCode=QR_CASHIER 或 payChannelCode=ALI_QR 或 payChannelCode=WX_NATIVE 时，payChannelExtra可以传payDataType设置返回支付数据支付类型。此时payDataType可以为：codeUrl-二维码地址,codeImgUrl-二维码图片地址，不传payDataType默认返回codeUrl类型, payChannelExtra示例数据如：{"payDataType": "codeImgUrl"}

当 payChannelCode=ALI_WAP 时，payChannelExtra可以传payDataType设置返回支付数据支付类型。此时payDataType可以为：form-返回自动跳转的支付表单,codeImgUrl-返回一个二维码图片URL,payUrl-返回支付链接，不传payDataType默认返回payUrl类型, payChannelExtra示例数据如：{"payDataType": "form"}

当 payChannelCode=ALI_PC 时，payChannelExtra可以传payDataType设置返回支付数据支付类型。此时payDataType可以为：form-返回自动跳转的支付表单,payUrl-返回支付链接，不传payDataType默认返回payUrl类型, payChannelExtra示例数据如：{"payDataType": "form"}

extJsonb

string

扩展参数

可选

商户扩展参数,回调时会原样返回
{
"readerCardNo" : "读者证卡号",
"readerIDNumber":"身份证号或护照号或唯一标识这个人的编号",
"readerName": "读者姓名",
"readerPhone":"读者联系电话",
"readerEmail":"读者邮箱",
"libCode": "读者所属分馆编码",
"operator":"操作人用户名"
}
注意：对于需要关联读者的业务，读者证号、身份证号或护照号或唯一标识这个人的编号、读者姓名是必需的；操作人用户名选填；读者所属分馆编码选填，Aleph费用支付可以填写读者所属馆的编码；

示例

{
    "appId": "90060",
    "channelPayOrderNo": "U12021022311124442600",
    "mchOrderNo": "20160427210604000490",
    "mchRefundNo": "M27210632100491",
    "refundAmount": "1000",
    "refundReason": "逾期费免除",
    "notifyUrl": "https://www.xxxx.com/notify.htm",
    "channelExtra": "{\"openid\": \"o6BcIwvSiRpfS8e_UyfQNrYuk2LI\"}",
    "extJsonb": "{\"readerCardNo\" : \"读者证号\",“readerName”: \"读者姓名\",\"libCode\": \"分馆编码\"}\n"
}

示例代码

Shell

JavaScript

Java

Swift

Go

PHP

Python

HTTP

C

C#

Objective-C

Ruby

OCaml

Dart

R

curl --location --request POST '/gateway-starter/api/gateway/240510611558401' \
--header 'lk-appid: 240479585243137' \
--header 'lk-time: 2025-04-08 16:29:13' \
--header 'lk-nonce: 9f96ac1ff4fa4595862f5709abce5eff' \
--header 'lk-sign: a37e073f77cde8428da6a9bf7750fac9' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "90060",
    "channelPayOrderNo": "U12021022311124442600",
    "mchOrderNo": "20160427210604000490",
    "mchRefundNo": "M27210632100491",
    "refundAmount": "1000",
    "refundReason": "逾期费免除",
    "notifyUrl": "https://www.xxxx.com/notify.htm",
    "channelExtra": "{\"openid\": \"o6BcIwvSiRpfS8e_UyfQNrYuk2LI\"}",
    "extJsonb": "{\"readerCardNo\" : \"读者证号\",“readerName”: \"读者姓名\",\"libCode\": \"分馆编码\"}\n"
}'

返回响应

🟢200成功

application/json

Body

code

integer

返回码

必需

返回码

cost

integer

响应速度

必需

响应速度

data

object

返回数据

必需

返回下单数据,json格式数据

code

string

返回状态

可选

COMMON_200-处理成功，其他-处理有误，详见错误码

msg

string

返回信息

可选

具体错误原因，例如：签名失败、参数格式校验错误

data

object

返回数据

可选

返回下单数据,json格式数据

msg

string

必需

responseTime

string

响应时间

必需

响应时间

success

boolean

成功与否

必需

成功与否

traceLogId

string

日志ID

必需

日志ID

示例

{
    "code": "COMMON_200",
    "msg": "SUCCESS",
    "data": {
        "channelOrderNo": "R202106181708358940000",
        "mchRefundNo": "M27210632100491",
        "refundState": "REFUND_PROGRESS",
        "errCode": "",
        "errMsg": ""
    }
}