diff --git a/docs/顺成汇创交易中心聚合支付/0接口接入指南.md b/docs/顺成汇创交易中心聚合支付/0接口接入指南.md new file mode 100644 index 0000000..b7be26f --- /dev/null +++ b/docs/顺成汇创交易中心聚合支付/0接口接入指南.md @@ -0,0 +1,44 @@ +在请求API的过程中，需要先获取Token凭证，才能请求之后的接口，为方便开发者快速上手财务交易中心的开发对接，token是调用财务交易中心API的凭证。 + +## 获取SecretId和SecretKey +需要先和财务交易中心联系，签署合同后，财务交易中心的人员会将SecretId和SecretKey发送给贵方。 + +## 生成Token +参考[获取接口调用凭据](https://www.yuque.com/shunchenghuichuang/iasgxw/uzstk1uxg8zeodr8)接口，传入上一步获取的SecretId和SecretKey获取Token。 + +以下是一些注意事项： + +1、token的有效期目前是1个小时，需定时刷新，重复获取将导致上次获取的token失效。 + +2、token是财务交易中心的全局唯一接口调用凭据，财务交易中心调用各接口时都需使用token。开发者需要进行妥善保存。 + +3、token的存储至少要保留512个字符空间。 + +4、在请求财务交易中心接口的时候，获取的token要放在请求头中。如下格式： + +`.header("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJJc1BheSI6IlRydWUiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1laWRlbnRpZmllciI6ImQ1ZTc3MzE2LTVjNWEtNDQ3OC1iZjZhLTQ2OWU2ODNlZDMyYyIsIm5iZiI6MTc2OTE1NzgwMywiZXhwIjoxNzY5MjQ0MjAzfQ.h7JEIFkoCfqAO-fjoVluGRA7JSB-5yj81_E2PVE8MEk")` + +## 接口签名加密 +在调用财务交易中心接口（获取接口调用凭据接口除外）时需要加签名，否则会无法调用接口。签名算法规则如下： + +1、获取所有支付接口传递参数的内容，剔除sign。 + +2、参数对象的“属性”剔除 值=Null和空字符串，参数对象的“属性” 值=对象时，对象序列化成json字符串，剔除 值=null,并且：参数的”键“按照 ASCII 码递增排序（字母升序排序）。 + +3、参数的”键“按照 ASCII 码递增排序（字母升序排序）。 + +4、将排序后的参数与其对应值，组合成参数=参数值 的格式，并且把这些参数用 & 字符连接起来，此时生成的字符串为业务字符串stringA；在业务字符串stringA后拼接上 &key=交易密钥。 + +5、进行MD5运算，将计算后的结果转换为小写，再将这个转小写的结果使用Base64编码，得到签名Sign。 + +## 接口域名 +测试域名：[https://cwpt-test.shunchenghc.com](http://cwpt-test.shunchenghc.com) + +正式域名：[https://main-platform.shunchenghc.com](https://main-platform.shunchenghc.com) + +## 请求参数 +大部分服务端 API 的请求方法为 `POST` 和 `GET`，对于接口参数，有固定的规范： + ++ 对于 GET 请求，请求参数应以 QueryString 的形式写在 URL 中。 ++ 对于 POST 请求，部分参数需以 QueryString 的形式写在 URL 中（如有额外参数会在文档里的 URL 中体现），其他参数如无特殊说明均以 JSON 字符串格式写在 POST 请求的 body 中。 ++ 交易相关接口返回参数类型为XML格式，其他接口为JSON格式。 diff --git a/docs/顺成汇创交易中心聚合支付/1.交易中心验签示例.md b/docs/顺成汇创交易中心聚合支付/1.交易中心验签示例.md new file mode 100644 index 0000000..ef4f5be --- /dev/null +++ b/docs/顺成汇创交易中心聚合支付/1.交易中心验签示例.md @@ -0,0 +1,76 @@ +```python +import json +import hashlib +import base64 +from typing import Any, Dict + +def build_sign(params: Dict[str, Any], secret_key: str) -> str: + """ + 生成签名 + :param secret_key: 交易密钥 + :return: 计算得到的sign值 + """ + # 1. 剔除值为None的键值对，并处理嵌套对象 + def process_value(value: Any) -> str: + if isinstance(value, dict): + # 处理对象：过滤null，排序键 + filtered_obj = {k: v for k, v in value.items() if v is not None} + # 按键排序 + sorted_keys = sorted(filtered_obj.keys()) + sorted_obj = {k: filtered_obj[k] for k in sorted_keys} + # 序列化为紧凑JSON + return json.dumps(sorted_obj, separators=(',', ':'), ensure_ascii=False) + elif isinstance(value, (list, tuple)): + # 列表/元组，直接序列化为紧凑JSON + return json.dumps(value, separators=(',', ':'), ensure_ascii=False) + else: + # 基本类型：字符串、数字、布尔 + return str(value) + + # 对顶层参数进行相同的处理：剔除值=null/空，剔除key="sign"，并处理嵌套对象 + filtered_params = {} + for key, value in params.items(): + if value is None or value == "" or key == "sign": + continue + filtered_params[key] = process_value(value) + + # 2. 按键ASCII升序排序 + sorted_keys = sorted(filtered_params.keys()) + # 3. 拼接成 stringA：key1=value1&key2=value2&... + stringA_parts = [] + for key in sorted_keys: + value = filtered_params[key] + # 值如果是字符串，直接使用；否则（理论上不会）转换为字符串 + stringA_parts.append(f"{key}={value}") + stringA = "&".join(stringA_parts) + + # 4. 追加 &key=密钥 + sign_str = stringA + f"&key={secret_key}" + + # 5. MD5运算 + md5_hash = hashlib.md5(sign_str.encode('utf-8')).digest() + # 6. 转小写（MD5结果通常是十六进制字符串，这里需要先转十六进制再小写） + md5_hex = md5_hash.hex().lower() + # 7. Base64编码 + sign = base64.b64encode(md5_hex.encode('utf-8')).decode('utf-8') + return sign + +# 示例用法 +if __name__ == "__main__": + # 假设请求参数如下 + params = { + + "reqSerialNo": "20260318110810747", + "data": { + "merchantId": "******", + "applyAmount": 10000, + "reqId": "******", + } + + + } + + secret_key = "******" # 替换为实际的交易密钥 + sign = build_sign(params, secret_key) + print(sign) +``` diff --git a/docs/顺成汇创交易中心聚合支付/2.获取接口调用凭据 copy.md b/docs/顺成汇创交易中心聚合支付/2.获取接口调用凭据 copy.md new file mode 100644 index 0000000..759eb41 --- /dev/null +++ b/docs/顺成汇创交易中心聚合支付/2.获取接口调用凭据 copy.md @@ -0,0 +1,63 @@ +接口应在服务端调用，不可在前端（小程序、网页、APP等）直接调用。具体可参考[接口接入指南](https://www.yuque.com/shunchenghuichuang/iasgxw/lw3ftk64nq0f2gsg)。 + +接口英文名：GetPayToken + +本接口用于获取获取全局唯一后台接口调用凭据token，token有效期为1个小时，开发者需要进行妥善保存，使用注意事项请参考[此文档](https://www.yuque.com/shunchenghuichuang/iasgxw/lw3ftk64nq0f2gsg)。 + +## 1、调用方式 +### HTTPS调用 +`POST /api/app/backend-account/pay-token` + +## 2、请求参数 +### 请求体 `Request Payload` +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| secretId | string | 是 | 账号的唯一凭证，需要联系财务交易中心获取 | +| secretKey | string | 是 | 唯一凭证密钥，需要联系财务交易中心获取 | + + +## 3、返回参数 +### 返回体 `Response Payload` +| 参数名 | 类型 | 说明 | +| :--- | :--- | :--- | +| respCode | string | 200是成功，其他值就是失败 | +| respMsg | string | 接口返回的信息，成功返回null | +| reqSerialNo | string | 接口请求流水号 | +| version | string | 接口版本 | +| data | string | 获取到的凭证 | + + +## 4、注意事项 +1、secretKey是账号使用财务交易中心API接口的密钥，请开发者妥善保存，避免因泄露造成账号被他人冒用等风险。 + +2、获取到的凭证，过期时间是1小时，请开发者妥善保存，并定时刷新新的凭证，避免后续业务出现问题。 + +## 5、代码示例 +请求参数： + +```json +{ +"secretId": "SEC-R******A", +"secretKey": "Lil7Rx**********G1UtW8"//签名时拼接使用的交易密钥 +} +``` + + + +返回参数： + +```json +{ +"respCode": "200",//200是成功，其他值就是失败 +"respMsg": null, +"reqSerialNo": "", +"version": "1.0", +"data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJJc1BheSI6IlRydWUiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1laWRlbnRpZmllciI6ImQ1ZTc3MzE2LTVjNWEtNDQ3OC1iZjZhLTQ2OWU2ODNlZDMyYyIsIm5iZiI6MTc2OTIyNDI1MiwiZXhwIjoxNzY5MzEwNjUyfQ.GdL_CG0LlgOmeNtbfc5eaogpd9A73VLT5pLbWziMqKo" +} +``` + + + + + + diff --git a/docs/顺成汇创交易中心聚合支付/3. 上传图片 copy.md b/docs/顺成汇创交易中心聚合支付/3. 上传图片 copy.md new file mode 100644 index 0000000..1e872c3 --- /dev/null +++ b/docs/顺成汇创交易中心聚合支付/3. 上传图片 copy.md @@ -0,0 +1,121 @@ +接口应在服务端调用，不可在前端（小程序、网页、APP等）直接调用。具体可参考[接口接入指南](https://www.yuque.com/shunchenghuichuang/iasgxw/lw3ftk64nq0f2gsg)。 + +接口英文名：UploadPic + +本接口用于上传图片信息。使用Form表单形式提交这些参数 + +## 1、调用方式 +### HTTPS调用 +`POST /api/app/upload` + +## 2、请求参数 +### 请求体 `Request Payload` +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| version | string | 否 | 版本号，服务商可自由定义 | +| reqSerialNo | string | 是 | 请求流水号(yyyyMMddHHmmssSSSXXXXX，其中 XXXXX为5位顺序号,禁止使用UUID等无意义数据) | +| sign | string | 是 | 签名 | +| media | File | 是 | 图片文件 | + + +## 3、返回参数 +### 返回体 `Response Payload` +| 参数名 | 类型 | 说明 | +| :--- | :--- | :--- | +| respCode | string | 200是成功，其他值就是失败 | +| respMsg | string | 接口返回的信息，成功返回null | +| reqSerialNo | string | 接口请求流水号 | +| version | string | 接口版本 | +| data | object | 图片地址 | + + +#### `data响应参数` +| 参数名 | 类型 | 说明 | +| :--- | :--- | :--- | +| photoUrl | string | 图片地址。
图片上传成功后，该图片保存在交易中心中的地址。
注：其他相关接口需要提供图片文件地址时，直接使用该地址即可。 | + + +## 4、注意事项 +1、content-type格式为multipart/form-data + +## 5、代码示例 +请求参数： + +```json +{ +"version": "1.0", +"reqSerialNo": "20221013152000", +"sign":"OWJmY2Q4OTQ1NDFhOTE4YzkxOWVhNTI2NGQ4MTE0ODM=", +"media":File +} +``` + + + +python示例： + +```python +import requests +import hashlib +import base64 +import datetime +import json +import os + +##定义流水号生成方法 +def reqSerialNo(): + now = datetime.datetime.now() + order_id = now.strftime("%Y-%m-%d-%H-%M-%S").replace("-", "") + return order_id + +def get_image_files(directory): + """获取指定目录及其子目录中的所有图片文件""" + image_extensions = {'.jpg', '.jpeg', '.png', '.gif', '.bmp', '.tiff', '.webp', '.ico'} + image_files = [] + for root, dirs, files in os.walk(directory): + for file in files: + ext = os.path.splitext(file)[1].lower() + if ext in image_extensions: + image_files.append(os.path.join(root, file)) + return image_files + + +##服务商参数 +path = r"D:\Document" ## 这里图片保存的路径 +img = "picture.png" +print(img) +file_name=os.path.join(img) ## 这里图片的名称 +request_url="http://localhost:19001/api/app/upload" ## 这里填写请求的接口地址 +token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJJc1BheSI6IlRydWUiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1laWRlbnRpZmllciI6ImQ1ZTc3MzE2LTVjNWEtNDQ3OC1iZjZhLTQ2OWU2ODNlZDMyYyIsIm5iZiI6MTc2NzA3NDUwNywiZXhwIjoxNzY3MTYwOTA3fQ.YxjyLi_f4kiluQGZBmfjteKokaPyzk1QkrrvgazErwc" + +file_md5 = hashlib.md5(open(file_name,'rb').read()).hexdigest() +files = {'media': open(file_name,'rb'),} + +body = { + "reqSerialNo" : "2025121316252900001", + "sign" : "MDc5NDNmMTE5ZjM2OTBhNjliYjk5MGUzYjllMjNiMTI=" + } +headers = { + "Authorization": f"Bearer {token}" + } + +files = {'media': open(file_name,'rb'),} +req = requests.post(url=request_url, data=body,files=files,headers=headers) ## 注：python的request请求在做post请求时会自动加上Content-Type: multipart/form-data;boundary=${bound}，因此本处可不填写headers +print(req.text) +``` + + + +返回参数： + +```json +{ + "respCode": "200",//200是成功，其他值就是失败 + "respMsg": "string", + "reqSerialNo": "string", + "version": "string", + "data": { + "photoUrl": "string" + } +} +``` diff --git a/docs/顺成汇创交易中心聚合支付/4.简易支付.md b/docs/顺成汇创交易中心聚合支付/4.简易支付.md new file mode 100644 index 0000000..6ae0cdd --- /dev/null +++ b/docs/顺成汇创交易中心聚合支付/4.简易支付.md @@ -0,0 +1,132 @@ +接口应在服务端调用，不可在前端（小程序、网页、APP等）直接调用。具体可参考[接口接入指南](https://www.yuque.com/shunchenghuichuang/iasgxw/lw3ftk64nq0f2gsg)。 + +接口英文名：SimplePay + +本接口用于发起简易支付。消费者可通过微信或者支付宝打开返回的支付链接进行支付。 + +1. 当前简易支付返回的支付链接为聚合链接，支持使用微信APP和支付宝APP打开进行支付。但是同一个简易支付链接，如果消费者已经使用微信APP打开过后，不可再使用支付宝APP打开再进行支付。 +2. 消费者用微信APP或者支付宝APP打开交易中心提供的简易支付链接后，需要1分钟内完成支付，如超时未支付，需要重新下单获取新的简易支付链接。 +3. 简易支付的原理是：消费者打开交易中心提供的简易支付链接后，由交易中心获取消费者在交易中心的APPID下的openid,并通过JSAPI的支付方式进行下单获取支付参数，最后唤起用户的付款页面。本质上该支付方式为JSAPI支付。 +4. 交易中心会根据业务的发展，视情况增加请求参数和返回参数，请服务商/商户侧提前做好兼容。 + +## 1、调用方式 +### HTTPS调用 +`POST /api/app/payOreder/simplePay` + +## 2、请求参数 +### 请求体 `Request Payload` +| 参数名 | 类型 | 必填 | 字段长度 | 说明 | +| :--- | :--- | :--- | :--- | :--- | +| service | string | 是 | - | 接口名称。此处固定值为：get_tdcode | +| t0 | string | 否 | 1 | D0交易标志，默认为0
0：D1交易
1：D0交易 | +| jspay_flag | string | 是 | 1 | 支付方式。
本处固定填写：2 | +| sign_type | string | 否 | 10 | 接口签名类型，枚举如下：
MD5：MD5签名算法
SM3：国密SM3签名算法 不传默认使用MD5算法 | +| merchant_id | string | 是 | 10 | 财务交易中心商户号 | +| third_order_id | string | 是 | 64 | 商户订单号。
由商户或者服务商自行定义，可以包含字母。需确保同一个商户下唯一 | +| amount | string | 是 | 10 | 订单金额。
单位为分，整数 | +| nonce_str | string | 是 | 32 | 随机字符串 | +| sign | string | 是 | 32 | 签名 | +| req_serial_no | string | 是 | 32 | 本次交易的请求流水号 | +| jump_url | string | 否 | - | 支付跳转地址。
当前跳转效果已不生效，服务商/商户可随意传一个地址, 或者不传该参数。 | +| user_name | string | 否 | - | 收银员名称 | +| notify_url | string | 否 | 128 | 交易通知地址。
接收财务交易中心通知的URL，需做UrlEncode 处理，需要绝对路径，确保顺成能正确访问，若不需要回调请忽略 | +| client_ip | string | 否 | 16 | 用户IP地址。
商户发起交易的IP地址 | +| body | string | 否 | 256 | 商品描述。不能包含回车、换行等特殊字符。
该信息会展示在微信付款页面的“商品”中 | +| shop_no | string | 否 | 16 | 商户门店编号。
只能是汉字、英文字母、数字 | +| attach | string | 否 | 96 | 附加数据。支付成功原样返回。
注意：只能是汉字、英文字母、数字 | +| limit_pay | string | 否 | 1 | 是否禁用信用卡，枚举如下：
1：禁止使用信用卡；
0或者不填：不限制 | +| goods_tag | string | 否 | 32 | 订单优惠标记，，代金券或立减优惠功能。
该参数财务交易中心透传给微信，当前仅对微信交易生效 | +| goods_detail | string | 否 | 8000 | 单品优惠商品详情。
该字段为JSON格式的字符串
1. 微信交易时，该参数透传给微信，对应微信的detail参数，主要用于微信的单品营销。
参数具体内容详见下方 | +| scene_info | string | 否 | - | 场景信息。
该字段用于上报场景信息，仅针对微信交易有效，透传至微信。目前支持上报实际门店信息。
该字段为JSON格式的字符串。
参数具体内容：{"store_info":{"id": "门店 ID","name ": "名称","area_code": "编码","address": "地址"}} | +| need_receipt | boolean | 否 | - | 电子发票功能。
仅针对微信交易有效，需要和微信公众平台的发票功能联合使用。枚举如下：
1. true
2. false
（只能为true或false，只支持全小写字母或全大写字母） | +| gps_info | string | 否 | 512 | gps信息。
校验GPS信息格式， 如：-128.12,23.1 -- 1. xxx,xxx -- 2. 经度xxx为[-180，180]之间的浮点数，维度 | +| bs_info | string | 否 | 512 | 基站信息。
校验基站信息格式,
格式说明： -- 1. 格式为：xxx,xxx,xxx,xxx 如：460,1,12,23454 -- 2. xxx均为整数，长度不超过11位
基站信息，从左至右依次对应以下几个字段： mcc: 移动国家号码，由3位数字组成，唯一地识别移动用户所属的国家。我国为460 mnc:移动网号，由两位数字组成，用于识别移动用户所归属的移动网 lac:位置区编码,为寻呼而设置的一个区域，覆盖一片地理区域，按寻呼量划分 ci :负责收发的天线所朝向的扇区编号 | + + +#### `goods_detail字段说明` +微信交易时，该参数对应透传至微信的detail参数 + +| 参数名 | 类型 | 必填 | 字段长度 | 说明 | +| :--- | :--- | :--- | :--- | :--- | +| cost_price | int | 否 | - | 订单原价。
1.商户侧一张小票订单可能被分多次支付，订 单原价用于记录整张小票的交易金额。
2.当订单原价与支付金额不相等，则不享受优惠。
3.该字段主要用于防止同一张小票分多次支 付，以享受多次优惠的情况，正常支付订单不 必上传此参数 | +| receipt_id | string | 否 | 32 | 商品小票 ID。商家小票 ID | +| goods_detail | object | 是 | - | 单品列表。
单品信息，使用 Json 数组格式提交 | +| ┗goods_id | string | 是 | 32 | 商品编码。
由半角的大小写字母、数字、中划线、下划线中的一种或几种组成 | +| ┗wxpay_goods _id | string | 否 | 32 | 微信侧商品编码。
微信支付定义的统一商品编号（没有可不传） | +| ┗goods_name | string | 否 | 256 | 商品名称。
商品的实际名称 | +| ┗quantity | int | 是 | - | 商品数量。
用户购买的数量 | +| ┗price | int | 是 | - | 商品单价。单位为：分。
如果商户有优惠，需传输商户优惠后的单价(例如：用户对一笔 100 元的订单使用了商场发的优惠券 100-50，则活动商品的单价应为原单价-50) | + + +#### `scene_info字段说明` +| 参数名 | 类型 | 必填 | 字段长度 | 说明 | +| :--- | :--- | :--- | :--- | :--- | +| id | string | 否 | 32 | 门店 id。门店唯一标识 | +| name | string | 否 | 64 | 门店名称 | +| area_code | string | 否 | 6 | 门店行政区划码。门店所在地行政区划码 | +| address | string | 否 | 128 | 门店详细地址 | + + +## 3、返回参数 +### 返回体 `Response Payload` +XML格式返回 + +| 参数名 | 类型 | 说明 | +| :--- | :--- | :--- | +| resp_code | string | 通信状态码。
200 - 成功。
非200 - 失败。
注：此字段是通信标识，业务状态要看result_code | +| resp_msg | string | 通信错误说明
resp_code非200时返回 | +| req_serial_no | string | 本次交易的请求流水号，原样返回 | +| 以下参数在resp_code=200时返回 | | | +| result_code | string | 业务状态码。
0 - 支付受理成功
非0 - 支付受理失败 | +| error_code | string | 支付失败错误码。
支付失败时返回
错误码 | +| error_msg | string | 支付失败原因。
支付失败时返回具体失败原因说明 | +| nonce_str | string | 随机字符串 | +| sign | string | 签名 | +| sign_type | string | 签名类型，枚举如下：
MD5：MD5签名算法
SM3：国密SM3签名算法 返回接口请求时设定的签名类型进行签名。 | +| cost_time | string | 请求耗时。
请求接口耗费的时间，单位毫秒 | +| merchant_id | string | 财务交易中心商户号 | +| third_order_id | string | 商户订单号。
由商户/服务商侧自主生成 | +| schc_order_id | string | 财务交易中心交易订单号 | +| 以下参数在result_code=0时返回 | | | +| jspay_url | string | 简易支付url。
重定向到该url可以完成后续支付流程。
返回二维码链接有效期为10分钟。
特别说明：获取该链接成功，并不一定代表该链接可进行支付。 | + + +## 4、注意事项 + + +## 5、代码示例 +请求参数： + +```json +{ + "service": "get_tdcode", + "jspay_flag": "2", + "sign_type": "MD5", + "merchant_id": "0000000038", + "third_order_id": "17730391726943A1F3E866823", + "amount": "1", + "nonce_str": "17730391726943A1F3E866823", + "req_serial_no": "17730391726943A1F3E866823", + "sign": "YzRkMTIzMDIzYWE0MTBkN2ExODY2ZTExNzVmNTI5MDg=" +} +``` + + + +返回参数： + +```html + + + + + + + + + + + + + +``` diff --git a/docs/顺成汇创交易中心聚合支付/5.支付交易结果查询.md b/docs/顺成汇创交易中心聚合支付/5.支付交易结果查询.md new file mode 100644 index 0000000..4723a3c --- /dev/null +++ b/docs/顺成汇创交易中心聚合支付/5.支付交易结果查询.md @@ -0,0 +1,219 @@ +接口应在服务端调用，不可在前端（小程序、网页、APP等）直接调用。具体可参考[接口接入指南](https://www.yuque.com/shunchenghuichuang/iasgxw/lw3ftk64nq0f2gsg)。 + +接口英文名：PaymentResultQuery + +该接口用于查询支付交易订单的支付结果。支持微信、支付宝、云闪付、数字货币等支付交易订单进行查询。 + +## 1、调用方式 +### HTTPS调用 +`POST /api/app/payOreder/PaymentResultQuery` + +## 2、请求参数 +### 请求体 `Request Payload` +| 参数名 | 类型 | 必填 | 字段长度 | 说明 | +| :--- | :--- | :--- | :--- | :--- | +| service | string | 是 | - | 接口名称。
此处固定值为：query_status | +| sign_type | string | 否 | 10 | 接口签名类型，枚举如下：
MD5：MD5签名算法
SM3：国密SM3签名算法 不传默认使用MD5算法 | +| merchant_id | string | 是 | 10 | 财务交易中心商户号 | +| third_order_id | string | 否 | 64 | 商户订单号。
third_order_id和schc_order_id两者必填其一，都填以schc_order_id为主 | +| schc_order_id | string | 否 | 16 | 顺成订单号。
third_order_id和schc_order_id两者必填其一，都填以schc_order_id为主。 | +| nonce_str | string | 是 | 32 | 随机字符串 | +| sign | string | 是 | 32 | 签名 | +| req_serial_no | string | 是 | 32 | 本次交易的请求流水号 | + + + + +## 3、返回参数 +### 返回体 `Response Payload` +XML格式返回 + +| 参数名 | 类型 | 说明 | +| --- | --- | --- | +| resp_code | string | 通信状态码。
200 - 成功。
非200 - 失败。
注：此字段是通信标识，业务状态要看result_code | +| resp_msg | string | 通信错误说明
resp_code非200时返回 | +| req_serial_no | string | 本次交易的请求流水号，原样返回 | +| 以下参数在resp_code=200时返回 | | | +| result_code | string | 业务状态码。
0 - 支付受理成功
非0 - 支付受理失败 | +| error_code | string | 支付失败错误码。
支付失败时返回
错误码 | +| error_msg | string | 支付失败原因。
支付失败时返回具体失败原因说明 | +| nonce_str | string | 随机字符串 | +| sign | string | 签名 | +| sign_type | string | 签名类型，枚举如下：
MD5：MD5签名算法
SM3：国密SM3签名算法 返回接口请求时设定的签名类型进行签名。 | +| cost_time | string | 请求耗时。
请求接口耗费的时间，单位毫秒 | +| merchant_id | string | 财务交易中心商户号 | +| sub_merchant_id | string | 通道商户号。
该顺成商户对应的上游商户号，即微信、支付宝、QRC商户号、QRA商户号、CUPS商户号等 | +| third_order_id | string | 商户订单号。
由商户/服务商侧自主生成 | +| pay_way | string | 支付类型。枚举如下：
WXZF：微信支付
ZFBZF：支付宝支付
UPSMZF：银联扫码支付
DCPAY：数字货币支付
UNKNOWN：未知支付方式 | +| 以下参数在result_code=0时返回 | | | +| schc_order_id | string | 财务交易中心交易订单号 | +| trade_type | string | 支付方式。枚举如下：
MICROPAY：付款码支付
NATIVE：Native支付，
JSAPI：JSAPI支付
SmPgPay：小程序支付，
JSAPIQuick：简易支付
FACEPAY：刷脸支付 | +| amount | string | 订单金额，单位：分 | +| status | string | 订单支付状态。枚举如下：
0：支付中
2：支付成功
6：订单关闭
8：支付失败 | +| channel_flag | string | 费率通道标记。枚举如下：
GXST：高校食堂
PUBWEL：公益
PUBPAY：公缴
OFFLINE:线下
ZFBLH：支付宝新蓝海
YLLZ: 微信绿洲
SLZXY：私立中小幼
INS：保险/教培
ONLINE：线上
当前仅微信、支付宝交易会返回 | +| interm_state | string | 支付中间态。
目前仅针对微信支付，订单为支付中时返回：NOTPAY,USERPAYING | +| 以下参数在status=2时返回 | | | +| bank_type | string | 支付银行卡类型。
消费者支付时使用的支付账户或者银行卡类型。
微信交易的银行类型
支付宝交易的银行类型
银联扫码交易的银行类型。枚举为：1-借记卡，2-贷记卡 | +| wxmp_fund_control | string | 小程序延迟结算订单管控状态
1 为冻结中，2 为已解冻 | +| openid | string | 消费者用户编号。
消费者在顺成机构下的唯一用户标识。 | +| sub_openid | string | 消费者用户编号。
status=2且微信和支付宝交易才返回。微信：商户公众号APPID下用户唯一标识；
支付宝：买家的支付宝用户ID
支付宝交易时openid和sub_openid一样。 | +| out_transaction_id | string | 账户机构订单号。即微信、支付宝、云闪付等订单号 | +| channel_order_id | string | 清算机构订单号。即银联、网联等清算机构的订单号 | +| channel_datetime | string | 通道支付成功时间。即消费者实际支付成功的时间。 | +| attach | string | 支付附加数据。
原样返回下单时上送的attach内容 | +| coupon | string | 支付宝红包金额，单位(分)。 | +| settlement_amount | string | 商户实付金额。商户实际结算金额，单位(分) | +| discount_amount | string | 订单优惠金额。单位(分) | +| promotion_detail | string | 优惠详情。参数具体内容详见下方 | +| buyer_pay_amount | string | 买家实付金额。
微信、支付宝、银联扫码、数字货币此值有效
数字货币时，该值=settle_amount | +| simple_url_flag | string | 简易支付标记。枚举如下：
1：简易支付，
0：非简易支付 | +| pay_time | string | 交易中心支付成功时间。
交易中心获取到该笔订单支付成功时在交易中心系统上记录下的时间 | +| device_info | string | 设备编号。
上游返回时才返 | +| store_id | string | 门店编号。
上游返回时才返 | +| iss_addn_data | string | 付款方附加数据。
返回商品维度优惠信息
仅银联扫码交易时返回，顺成仅透传银联返回的信息。参数内容详见下方 | +| hb_fq_num | string | 花呗分期期数。
支付宝花呗分期交易时返回。
注：该信息为顺成系统中保存的，信息，不代表该笔交易为花呗分期交易，如果交易时指定花呗分期，顺成系统会保存该数据，但是消费者可能在支付时选择了其他方式支付。 | +| alipay_infos | string | 支付宝拓展参数。仅支付宝交易时返回，JSON格式。
本处透传支付宝返回的参数。
参数具体内容详见下方 | + + +注：以上参数的必填性，只有在符合的前提下才是必填，比如pay_time参数，只有在resp_code=200且result_code=0且status=2时，才会返回，任一条件不满足均不返回。 + +#### `微信promotion_detail字段说明` +| 参数名 | 类型 | 说明 | +| --- | --- | --- | +| promotion_id | string | 券ID。券或者立减优惠ID | +| name | string | 优惠名称 | +| scope | string | 优惠范围。枚举如下：
GLOBAL- 全场代金券
SINGLE- 单品优惠 | +| type | string | 优惠类型。枚举如下：
COUPON- 代金券，需要走结算资金的充
值型代金券,（境外商户券币种与支付币种
一致）
DISCOUNT- 优惠券，不走结算资金的免
充值型优惠券，（境外商户券币种与标价币
种一致 | +| amount | int | 优惠券面额。用户享受优惠的金额（优惠券面额=微信出
资金额+商家出资金额+其他出资方金额 ） | +| activity_id | string | 活动ID。在微信商户后台配置的批次 ID | +| wxpay_contribute | int | 微信出资金额。
特指由微信支付商户平台创建的优惠，出
资金额等于本项优惠总金额，单位为分 | +| merchant_contribute | int | 商户出资金额。
特指商户自己创建的优惠，出资金额等于
本项优惠总金额，单位为分 | +| other_contribut
e | int | 其他出资金额。
其他出资方出资金额，单位为分 | +| currency | string | CNY：人民币，境内商户号仅支持人民币 | +| goods_detail | object | 单品信息，使用 Json 格式 | +| ┖goods_id | string | 商品编码。
由半角的大小写字母、数字、中划线、下划线中的一种或几种组成 | +| ┖goods_remark | string | 商品备注。
goods_remark 为备注字段，按照配置原样返回，
字段内容在微信后台配置券时进行设置。 | +| ┖discount_amount | int | 商品优惠金额。单品的总优惠金额，单位为：分 | +| ┖quantity | int | 商品数量。
用户购买的数量 | +| ┖price | int | 商品价格。
单位为：分。如果商户有优惠，需传输商户优惠
后的单价(例如：用户对一笔100元的订单使用了
商场发的纸质优惠券 100-50，则活动商品的单价
应为原单价-50) | + + +#### `支付宝promotion_detail字段说明` +该参数对应支付宝的voucher_detail_list参数。本交易支付时使用的所有优惠券信息。只有在 query_options 中指定时才返回该字段信息。 + +| 参数名 | 类型 | 说明 | +| --- | --- | --- | +| id | string | 券ID | +| name | string | 券名称 | +| type | string | 当前有三种类型：
ALIPAY_FIX_VOUCHER - 全场代金券;
ALIPAY_DISCOUNT_VOUCH ER -折扣券;
ALIPAY_ITEM_VOUCHER - 单品优惠;
注：不排除将来新增其他类型的可能，商家接入时注意兼容性避免硬编码 | +| amount | decimal | 优惠券面额，它应该会等于商家出资加上其他出资方出资 | +| merchant_contribute | decimal | 商家出资（特指发起交易的商家出资金额） | +| other_contribut
e | decimal | 其他出资方出资金额，可能是支付宝，可能是品牌商，或者其他方，也可能是他们的一起出资 | +| memo | string | 优惠券备注信息 | +| template_id | string | 券模板 id | +| other_contribute_detail | object | 优惠券的其他出资方明细 | +| ┖contribute_type | string | 出资方类型，如品牌商出资、支付宝平台出资等 | +| ┖contribute_amount | decimal | 出资方金额 | +| purchase_buyer_contribute | decimal | 如果使用的这张券是用户购买的，则该字段代表用户在购买这张券时用户实际付款的金额 | +| purchase_merchant_contribute | decimal | 如果使用的这张券是用户购买的，则该字段代表用户在购买这张券时商户优惠的金额 | +| purchase_ant_contribute | decimal | 如果使用的这张券是用户购买的，则该字段代表用户在购买这张券时平台优惠的金额 | + + +#### `银联扫码promon_detail字段说明` +对应银联二维码平台的 couponInfo 参数。本域采用JSON格式，以方便扩展。本域全部内容用“[ ]”包含；内部可含多个对象，每个 对象用“{ }”包含，对象之间以“,”分隔；对象内可含多个子域，子域间以“,”分隔，子域采取"key":"value"的形式，key和value都需要用双引号包裹。子域定义如下表： + +| 参数名 | 类型 | 说明 | +| --- | --- | --- | +| id | string | 项目编号。票券编号、活动编号等，格式自定义 | +| desc | string | 项目简称。优惠活动简称，可用于展示、打单等 | +| type | string | 项目类型,枚举如下：
DD01：随机立减
CP01：抵金券1：无需领取，交易时直接适配并承兑的优惠券
CP02 ：抵金券2：事前领取，交易时上送银联并承兑的优惠券
未来将根据业务发展增加新的类型。 | +| spnsrId | string | 出资方。
银联作为出资方：固定填写 00010000； 付款方作为出资方：填写 8 位付款方机 构代码； 商户作为出资方：填写 15 位商户代码 | +| offstAmt | int | 抵消交易金额。不能为全 0。币种同上层 currencyCode
字段 | +| addnInfo | string | 附加信息。内容自定义 | + + +#### `iss_addn_data字段说明` +本域采用JSON格式，全部内容用“{ }”包含，内部可包含 +多个子域。目前仅包含“商品优惠信息dctDetail”子域，后续将根据业务需要新增子域。 + +| 参数名 | 类型 | 说明 | +| --- | --- | --- | +| dctDetail | object | 商品优惠明细内容.
商品优惠信息dctDetail子域采用嵌套JSON格式，全部内容用“[ ]”包含，内部可含多个对象，每个对象用“{ }”包含，对象之间以“,”分隔；对象内可含多个字段，字段间以 “,”分隔 | +| ┖id | string | 参与优惠的商品编号 | +| ┖dctId | string | 优惠活动的编号 | +| ┖dctQuantity | string | 参与优惠的商品数量，示例： 本商品数量为10，其中2件参与了优惠，则本字段值为2 | +| ┖dctPrice | int | 商品的优惠金额，以分为单位，示例： 商品单价10元，共5件，其中2件参与优惠，每件优惠3元，则本字段值为600
字段 | +| ┖addnInfo | string | 内容自定义 | + + +#### `alipay_infos字段说明` +| 参数名 | 类型 | 说明 | +| --- | --- | --- | +| total_amount | decimal | 交易金额(单位:分, 类型:数字) | +| settle_amount | string | 结算币种订单金额 | +| pay_amount | string | 支付币种订单金额 | +| receipt_amount | string | 实收金额(单位:分, 类型:数字) | +| point_amount | int | 使用集分宝付款的金额 | +| invoice_amount | decimal | 交易中可给用户开具发票的金额(单位:元) | +| fund_bill_list | Array | 交易支付使用的资金渠道。只有在签约中指定需要返回资金明细，或者入参的query_options 中指定时才返回该字段信息。 | +| card_balance | Price | 支付宝卡余额 | +| store_name | string | 发生支付交易的商户门店名称 | +| discount_goods_detail | string | 本次交易支付所使用的单品券优惠的商品优惠信息。只有在 query_options中指定时才返回该字段信息。 | +| async_payment_mode | string | 异步支付模式，先享后付业务会返回该参数，目前有三种值：ASYNC_DELAY_PAY( 异步延时付款); ASYNC_REALTIME_PAY( 异步准实时付款); SYNC_DIRECT_PAY(同步直接扣款); | +| purchase_merchant_contribute | Price | 如果使用的这张券是用户购买的，则该字段代表用户在购买这张券时商户优惠的金额 | +| auth_trade_pay_mode | string | 预授权支付模式，该参数仅在信用预授权支付场景下返回。信用预授权支付：CREDIT_PREAUTH_PAY | +| advance_amount | string | 先享后付 2.0 垫资金额,不返回表示没有走垫资，非空表示垫资支付的金额 | +| business_params | string | 商户传入业务信息，具体值要和支付宝约定将商户传入信息分发给相应系统，应用于安全，营销等参数直传场景格式为 json 格式 | +| buyer_user_type | string | 买家用户类型。 CORPORATE:企业用户；PRIVATE:个人用户 | +| buyer_user_name | string | 买家名称；买家为个人用户时为买家姓名，买家为企业用户时为企业名称； | +| mdiscount_amount | string | 商家优惠金额 | +| discount_amount | string | 平台优惠金额 | +| charge_flags | string | 费率活动标识，当交易享受活动优惠费率时，返回该活动的标识；(1)蓝海活动优惠费率 0，值为 bluesea_1(2) 特 殊 行 业 优 惠 费 率 0 ， 值 为industry_special_00(3) 特殊行业优惠费率千一，值为industry_special_01 | +| buyer_logon_id | string | 买家支付宝账号 | +| hb_fq_pay_info | object | 支付宝花呗分期详情。JSON格式
该笔交易为花呗分期交易时返回。
user_install_num：分期期数
fq_amount ：分期金额，单位：元
注：该参数顺成仅做透传，有时该参数为JSON格式的字符串，样式为：
{\"USER_INSTALL_NUM\":\"3\"，\"FQ_AMOUNT\":\"700\"} ,请做好兼容 | + + +## 4、注意事项 + + +## 5、代码示例 +请求参数： + +```json +{ + "service": "query_status", + "merchant_id": "0000000018", + "third_order_id": "T20220930091913k3lERPTS", + "nonce_str": "JohCmBiL", + "sign": "4A5795878AE4FF29E6A8B9C8DB17DF69", + "req_serial_no":"17730391726943A1F3E866823" +} + +``` + + + +返回参数： + +```html + + + + + + + + + + + + + + + + + + + + +``` diff --git a/docs/顺成汇创交易中心聚合支付/6. 退款交易.md b/docs/顺成汇创交易中心聚合支付/6. 退款交易.md new file mode 100644 index 0000000..43a5fd4 --- /dev/null +++ b/docs/顺成汇创交易中心聚合支付/6. 退款交易.md @@ -0,0 +1,111 @@ +接口应在服务端调用，不可在前端（小程序、网页、APP等）直接调用。具体可参考[接口接入指南](https://www.yuque.com/shunchenghuichuang/iasgxw/lw3ftk64nq0f2gsg)。 + +接口英文名：OrderRefund + +该接口用于对支付成功的订单进行退款。支持全额退款和部分退款。 + +## 1、调用方式 +### HTTPS调用 +`POST /api/app/refundOrder/orderRefund` + +## 2、请求参数 +### 请求体 `Request Payload` +| 参数名 | 类型 | 必填 | 字段长度 | 说明 | +| :--- | :--- | :--- | :--- | :--- | +| service | string | 是 | - | 接口名称。
此处固定值为：unified_refund | +| sign_type | string | 否 | 10 | 接口签名类型，枚举如下：
MD5：MD5签名算法
SM3：国密SM3签名算法 不传默认使用MD5算法 | +| merchant_id | string | 是 | 10 | 财务交易中心商户号 | +| schc_order_id | string | 否 | 16 | 财务交易中心订单号。
schc_order_id和third_order_id两者必填其一，都填优先使用schc_order_id。
如商户/服务商需要退3个月以上的交易，必须使用schc_order_id发起退款 | +| third_order_id | string | 否 | 64 | 商户订单号。
schc_order_id和third_order_id两者必填其一，都填优先使用schc_order_id。 | +| merchant_refund_id | string | 是 | 64 | 商户退款订单号。
由商户/服务商生成，支持数字字母格式，不能包括“_”等特殊字符，需要确认在商户下唯一。 | +| refund_amount | string | 是 | 10 | 退款金额，单位：分。
可进行部分退款，不可超退。 | +| refund_type | string | 否 | 1 | 退款出资类型。
0：当日正向交易抵扣退款
1：可用商户账户余额退款（优先使用正向交易抵扣，正向交易不够抵扣情况下可用账户余额进行退款）
2：只可用商户账户余额退款。
特别说明：1. 原交易订单为跑批清分时，该参数默认为1，传值则按传值对应模式校验能否退款。
原交易订单为实时清分时，无论传几均默认按2处理，即从商户账户余额退款 | +| nonce_str | string | 是 | 32 | 随机字符串 | +| sign | string | 是 | 32 | 签名 | +| req_serial_no | string | 是 | 32 | 本次交易的请求流水号 | +| notify_url | string | 否 | 128 | 交易通知地址。
接收财务交易中心通知的URL，需做UrlEncode 处理，需要绝对路径，确保顺成能正确访问，若不需要回调请忽略 | +| shop_no | string | 否 | 16 | 商户门店编号。
只能是汉字、英文字母、数字 | +| attach | string | 否 | 96 | 附加数据。支付成功原样返回。
注意：只能是汉字、英文字母、数字 | + + +## 3、返回参数 +### 返回体 `Response Payload` +XML格式返回 + +| 参数名 | 类型 | 说明 | +| :--- | :--- | --- | +| resp_code | string | 通信状态码。
200 - 成功。
非200 - 失败。
注：此字段是通信标识，业务状态要看result_code | +| resp_msg | string | 通信错误说明
resp_code非200时返回 | +| cost_time | string | 请求耗时。
请求接口耗费的时间，单位毫秒 | +| req_serial_no | string | 本次交易的请求流水号，原样返回 | +| 以下参数在resp_code=200时返回 | | | +| result_code | string | 业务状态码。
0 - 退款受理成功
非0 - 退款受理失败
注：退款受理成功不代表退款成功，具体请结合该笔订单的状态status来确定退款结果 | +| error_code | string | 退款失败错误码。
退款失败时返回
错误码 | +| error_msg | string | 退款失败原因。
退款失败时返回具体失败原因说明 | +| nonce_str | string | 随机字符串 | +| sign | string | 签名 | +| sign_type | string | 签名类型，枚举如下：
MD5：MD5签名算法
SM3：国密SM3签名算法 返回接口请求时设定的签名类型进行签名。 | +| merchant_id | string | 财务交易中心商户号 | +| third_order_id | string | 商户订单号。
商户原支付交易订单号 | +| sub_merchant_id | string | 通道商户号。
该笔订单交易时所使用的上游商户号，即微信商户号、或者支付宝商户号、或者银联商户号等 | +| 以下参数在result_code=0时返回 | | | +| schc_order_id | string | 顺成交易订单号。
该笔退款交易对应的原支付交易订单号。 | +| status | string | 订单支付状态，枚举如下：
10：退款中
11：退款成功
12：退款失败 | +| refund_amount | string | 退款金额，单位：分 | +| buyer_refund_amount | string | 买家实际退款金额，单位：分 | +| merchant_refund_id | string | 商户退款订单号。 | +| schc_refund_id | string | 交易中心退款订单号。
退款受理成功后，会返回该笔退款对应的交易中心退款交易订单号。 | +| amount | string | 订单总金额。单位：分。
退款情况下，amount和total_amount数值一样。 | +| total_amount | | 订单总金额。单位：分。
退款情况下，amount和total_amount数值一样。 | +| order_balance | string | 订单剩余可退金额。单位：分。
本次退款后，订单剩余可继续发起退款的金额 | +| attach | string | 退款附加数据。
原样返回退款请求时上送的attach内容。如果请求时没有上送attach参数，则不返回。
注意：只能是汉字、英文字母、数字 | + + +## 4、注意事项 + + +## 5、代码示例 +请求参数： + +```json +{ + "service": "unified_refund", + "sign_type": "MD5", + "merchant_id": "123456789", + "schc_order_id": "0000273593826042", + "third_order_id": "17707745873403A1F3E866823", + "merchant_refund_id": "17708871997883A1F3E866823", + "refund_amount": "1", + "nonce_str": "17707745873403A1F3E866823", + "sign": "YWU5NDgyNzIwZTc3MTRkZGU4YTY2OTQ2MzE0N2VmMjY=", + "req_serial_no": "17707745873403A1F3E866823" +} +``` + + + +返回参数： + +```html + + + + + + + + + + + + + + + + + + + + + +``` diff --git a/docs/顺成汇创交易中心聚合支付/7.退款查询.md b/docs/顺成汇创交易中心聚合支付/7.退款查询.md new file mode 100644 index 0000000..79df102 --- /dev/null +++ b/docs/顺成汇创交易中心聚合支付/7.退款查询.md @@ -0,0 +1,140 @@ +接口应在服务端调用，不可在前端（小程序、网页、APP等）直接调用。具体可参考[接口接入指南](https://www.yuque.com/shunchenghuichuang/iasgxw/lw3ftk64nq0f2gsg)。 + +接口英文名：OrderRefundQuery + +该接口用于查询退款交易订单的退款结果。 + +## 1、调用方式 +### HTTPS调用 +`POST /api/app/refundOrder/orderRefundQuery` + +## 2、请求参数 +### 请求体 `Request Payload` +| 参数名 | 类型 | 必填 | 字段长度 | 说明 | +| :--- | :--- | :--- | :--- | --- | +| service | string | 是 | - | 接口名称。
此处固定值为：unified_query_refund | +| sign_type | string | 否 | 10 | 接口签名类型，枚举如下：
MD5：MD5签名算法
SM3：国密SM3签名算法 不传默认使用MD5算法 | +| merchant_id | string | 是 | 10 | 财务交易中心商户号 | +| schc_order_id | string | 否 | 16 | 财务交易中心订单号。
schc_order_id和third_order_id两者必填其一，都填优先使用schc_order_id。
如商户/服务商需要退3个月以上的交易，必须使用schc_order_id发起退款 | +| third_order_id | string | 否 | 64 | 商户订单号。
schc_order_id和third_order_id两者必填其一，都填优先使用schc_order_id。 | +| merchant_refund_id | string | 否 | 64 | 商户退款订单号。
merchant_refund_id和schc_refund_id两者必填其一，都填优先使schc_refund_id | +| schc_refund_id | string | 否 | 16 | 交易中心退款订单号。
merchant_refund_id和schc_refund_id两者必填其一，都填优先使schc_refund_id | +| nonce_str | string | 是 | 32 | 随机字符串 | +| sign | string | 是 | 32 | 签名 | +| req_serial_no | string | 是 | 32 | 本次交易的请求流水号 | + + +## 3、返回参数 +### 返回体 `Response Payload` +XML格式返回 + +| 参数名 | 类型 | 说明 | +| :--- | :--- | --- | +| resp_code | string | 通信状态码。
200 - 成功。
非200 - 失败。
注：此字段是通信标识，业务状态要看result_code | +| resp_msg | string | 通信错误说明
resp_code非200时返回 | +| cost_time | string | 请求耗时。
请求接口耗费的时间，单位毫秒 | +| req_serial_no | string | 本次交易的请求流水号，原样返回 | +| 以下参数在resp_code=200时返回 | | | +| result_code | string | 业务状态码。
0 - 退款查询受理成功
非0 - 退款查询受理失败
注：这里只代表本次退款查询请求的业务受理结果，为0不代表退款成功，具体请结合该笔订单的状态status来确定退款结果 | +| error_code | string | 退款失败错误码。
退款失败时返回
错误码 | +| error_msg | string | 退款失败原因。
退款失败时返回具体失败原因说明 | +| nonce_str | string | 随机字符串 | +| sign | string | 签名 | +| sign_type | string | 签名类型，枚举如下：
MD5：MD5签名算法
SM3：国密SM3签名算法 返回接口请求时设定的签名类型进行签名。 | +| merchant_id | string | 财务交易中心商户号 | +| third_order_id | string | 商户订单号。
商户原支付交易订单号 | +| sub_merchant_id | string | 通道商户号。
该笔订单交易时所使用的上游商户号，即微信商户号、或者支付宝商户号、或者银联商户号等 | +| mch_balance_refund | string | 商户退款类型。枚举如下：
0：未使用账户余额退款，
1：使用账户余额退款 | +| 以下参数在result_code=0时返回 | | | +| schc_order_id | string | 交易中心交易订单号。
该笔退款交易对应的原支付交易订单号。 | +| status | string | 订单支付状态，枚举如下：
10：退款中
11：退款成功
12：退款失败 | +| refund_amount | string | 退款金额，单位：分 | +| buyer_refund_amount | string | 买家实际退款金额，单位：分 | +| merchant_refund_id | string | 商户退款订单号。 | +| schc_refund_id | string | 交易中心退款订单号。
退款受理成功后，会返回该笔退款对应的交易中心退款交易订单号。 | +| amount | string | 订单总金额。单位：分。
退款情况下，amount和total_amount数值一样。 | +| total_amount | | 订单总金额。单位：分。
退款情况下，amount和total_amount数值一样。 | +| order_balance | string | 订单剩余可退金额。单位：分。
本次退款后，订单剩余可继续发起退款的金额 | +| attach | string | 退款附加数据。
原样返回退款请求时上送的attach内容。如果请求时没有上送attach参数，则不返回。
注意：只能是汉字、英文字母、数字 | +| 以下参数在status=11时返回 | | | +| refund_time | string | 退款成功时间
银联/网联返回的退款成功时间 | +| channel_order_id | string | 通道退款订单号。
银联/网联返回的退款订单号。 | +| settlement_refund_amount | string | 实际退款金额。 | +| discount_refund_amount | string | 折扣优惠退款金额 | +| refund_detail | string | 退款优惠详情。
优惠退款功能信息，本字段为json 数组，详见下方
当前仅微信交易且有退款优惠时会返回具体内容。 | +| refund_detail_item_list | string | 本次退款使用的资金渠道详情，本字段为json 数组。详见下方 | + + +#### `子域参数refund_detail` +| 参数名 | 类型 | 说明 | +| --- | --- | --- | +| promotion_id | string | 券 ID 。券或者立减优惠 id | +| scope | string | 优惠范围。枚举如下：
GLOBAL：全场代金券
SINGLE：单品优惠 | +| type | string | 优惠类型，枚举如下：
COUPON：代金券，需要走结算资金的充值型代金券（境外商户券币种 , 与支付币种一 致）
DISCOUNT：优惠券，不走结算资金 的免充 值型优惠券，（境外商户券币种与标价币种 一致 | +| amount | Int | 优惠券面额。
用户享受优惠的金额 | +| refund_amount | Int | 优惠券退款额。
按比例退款的优惠券金额 | + + +#### `子域参数refund_detail_item_list ` +| 参数名 | 类型 | 说明 | +| :--- | :--- | :--- | +| fund_channel | string | 交易使用的资金渠道 | +| amount | Int | 该支付工具类型所使用的金额 | +| real_amount | Int | 渠道实际付款金额 | +| fund_type | string | 渠道所使用的资金类型,目前只在资金渠道(fund_channel)是银行卡渠道(BANKCARD)的情况下才返回该信息
借记卡:：DEBIT_CARD
信用卡：CREDIT_CARD
借贷合一卡：MIXED_CARD | + + +## 4、注意事项 +如果退款交易受理未成功，请不要调退款交易查询接口查询退款结果。 + +## 5、代码示例 +请求参数： + +```json +{ + "service": "unified_query_refund", + "sign_type": "MD5", + "merchant_id": "12345678", + "schc_order_id": "0000195193826041", + "third_order_id": "17706897023453A1F3E7C48C6", + "merchant_refund_id": "17707042941793A1EC2429D75", + "schc_refund_id": "0000755593826041", + "nonce_str": "JohCmBiL", + "sign": "ZTkyNzJkYmY2MTAxNWNmZDM0YjRlZmY3YzA3YzRmODA=", + "req_serial_no": "17706897023453A1F3E7C48C6" +} +``` + + + +返回参数： + +```html + + + + + + + + + + + + + + + + + + + + + + + + + + + +```