交易明细文件下载接口文档
目录
1概述
1.1请求规则
| 规则名称 | 描述 |
|---|---|
| 请求地址(测试环境) | |
| 请求方式 | GET/POST |
| 参数格式 | application/json |
| 字符编码 | 统一采用UTF-8字符编码 |
1.2安全控制
系统采用如下方式保证产品需求方平台的安全性
- 平台各接口支持HTTPS协议。
- 访问任意接口都需要验证签名才能访问。
2接口说明
2.1支付交易文件下载
- 接口地址
/api/opendata/openpay/getPayTransFile`
功能说明
1、该文件每日凌晨按交易日期前一日自动生成。如当日未发生任何交
易，则只生成一个空文件。文件中包含当日发生的所有支付交易明细，包括：消费成功/失败交易数据；
2、文件内包含当日交易明细。金额统一使用分为单位。请求方式
请求方法: POST
Content-Type: application/json
编码方式: UTF-8
- 请求方式
请求方法: POST
Content-Type: application/json
编码方式: UTF-8
- 请求参数
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| orgId | int | 否(和merchantId不能同时为空) | 123 | 由平台线下提供 |
| merchantId | int | 否(和orgId不能同时为空) | 123 | 由平台线下提供 |
| transDate | string | 是 | 20230708 | 格式为yyyyMMdd |
| timestamp | Long | 是 | 1574651175506 | 时间戳，以毫秒为单位 |
| sign | string | 是 | 签名，详见签名规则 | |
| appKey | string | 是 | fwzc8EtxzIfX9Ql3Hmgh |
- 返回值
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| code | int | 是 | 200 | 响应状态码 |
| msg | string | 是 | 签名错误 | 返回状态码信息 |
| data | object | 否 | 返回结果 |
data返回值说明
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| url | string | 是 | 交易文件下载地址. |
文件格式说明
csv 文件格式，第一行标题.
| 字段名称 | 描述 |
|---|---|
| 支付订单号 | 平台支付订单号 |
| 外部支付订单号 | 应用方提供的支付订单号 |
| 项目ID | 应用接入支付项目ID，同查询参数 |
| 支付渠道ID | 支付方式ID |
| 支付渠道 | 饭卡、微信、支付宝等 |
| 商户id | 支付商户id |
| 微信支付商户id | 微信支付商户id |
| 用户标识 | 卡号、手机号等 |
| 用户ID | 系统中用户唯一标识，微信扫码支付时为空 |
| 实付金额 | 用户实际支付金额（可能会加收服务费或优惠），单位分 |
| 支付状态 | 是否支付成功 SUCCESS代表成功 |
| 支付时间 | 2023-07-02 15:24:30 |
2.2退款交易文件下载
- 接口地址
/api/opendata/openpay/getRefundTransFile`
功能说明
1、该文件每日凌晨按交易日期前一日自动生成。如当日未发生任何交
易，则只生成一个空文件。文件中包含当日发生的所有支付交易明细，包括：退款成功/失败交易数据；
2、文件内包含当日交易明细。金额统一使用分为单位。请求方式
请求方法: POST
Content-Type: application/json
编码方式: UTF-8
- 请求方式
请求方法: POST
Content-Type: application/json
编码方式: UTF-8
- 请求参数
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| orgId | int | 否(和merchantId不能同时为空) | 123 | 由平台线下提供 |
| merchantId | int | 否(和orgId不能同时为空) | 123 | 由平台线下提供 |
| transDate | string | 是 | 20230708 | 格式为yyyyMMdd |
| timestamp | Long | 是 | 1574651175506 | 时间戳，以毫秒为单位 |
| sign | string | 是 | 签名，详见签名规则 | |
| appKey | string | 是 | fwzc8EtxzIfX9Ql3Hmgh |
- 返回值
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| code | int | 是 | 200 | 响应状态码 |
| msg | string | 是 | 签名错误 | 返回状态码信息 |
| data | object | 否 | 返回结果 |
data返回值说明
| 字段名称 | 描述 |
|---|---|
| 退款订单号 | 平台退款订单号 |
| 第三方退款订单号 | 第三方退款订单号 |
| 支付订单号 | 平台支付订单号 |
| 第三方支付订单号 | 第三方支付订单号 |
| 项目ID | 应用接入支付项目ID，同查询参数 |
| 支付渠道ID | 支付时的付款渠道，退款是原路返回 |
| 支付渠道 | 饭卡、微信、支付宝等 |
| 用户标识 | 卡号、手机号等 |
| 用户ID | 系统中用户唯一标识，微信扫码支付时为空 |
| 退款金额 | 用户实际退款金额，单位分 |
| 退款状态 | 是否退款成功 SUCCESS代表成功 |
| 退款时间 | 2023-07-02 15:24:30 |
3签名规则
3.1签名介绍
调用接口都需要携带签名,服务端会根据请求参数,对签名进行校验,签名不合法的请求将会被拒绝。
3.2签名方法
以接口/api/opendata/userquery为例
请求的参数如下
appKey：
fwzc8EtxzIfX9Ql3Hmghtimestamp：
1680580829000userId：
ZZGX20230404173443981
平台方提供的密钥secretKey为77f44bf82004154f763a2eb4fa096487a017fe9c
- 将请求参数中除appKey、sign外的多个键值对,根据键按照字典序排序,并按照
key1=value1&key2=value2...的格式拼成一个字符串。
string str = "userId=ZZGX20230404173443981×tamp=1680580829000";- 将secretKey拼接在第一步中排序后的字符串后面得到待签名字符串。
string signTemp = str + "&secretKey=77f44bf82004154f763a2eb4fa096487a017fe9c";
//userId=ZZGX20230404173443981×tamp=1680580829000&secretKey=77f44bf82004154f763a2eb4fa096487a017fe9c- 对待签名字符串求MD5摘要并转为大写即为sign：
4CC2EB02383141C666F14D0EE681FB7A
需要注意以下规则
| code状态码 | 说明 |
|---|---|
| 200 | 成功 |
| 500 | 失败 |
