交易明细文件下载接口文档

目录

1概述

1.1请求规则

规则名称 描述
请求地址(测试环境)
请求方式 GET/POST
参数格式 application/json
字符编码 统一采用UTF-8字符编码

1.2安全控制

系统采用如下方式保证产品需求方平台的安全性

  1. 平台各接口支持HTTPS协议。
  2. 访问任意接口都需要验证签名才能访问。

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:fwzc8EtxzIfX9Ql3Hmgh

  • timestamp:1680580829000

  • userId:ZZGX20230404173443981

平台方提供的密钥secretKey为77f44bf82004154f763a2eb4fa096487a017fe9c

  1. 将请求参数中除appKey、sign外的多个键值对,根据键按照字典序排序,并按照key1=value1&key2=value2...的格式拼成一个字符串。
string str = "userId=ZZGX20230404173443981&timestamp=1680580829000";
  1. 将secretKey拼接在第一步中排序后的字符串后面得到待签名字符串。
string signTemp = str + "&secretKey=77f44bf82004154f763a2eb4fa096487a017fe9c";
//userId=ZZGX20230404173443981&timestamp=1680580829000&secretKey=77f44bf82004154f763a2eb4fa096487a017fe9c
  1. 对待签名字符串求MD5摘要并转为大写即为sign:4CC2EB02383141C666F14D0EE681FB7A

需要注意以下规则

  1. 请求参数的值为空值(null)则不参与签名,请求参数的值为空字符串(“”)则会参与签名
  2. 参数名区分大小写
  3. appKey、sign参数不参与签名

    附录:结果码code说明

code状态码 说明
200 成功
500 失败
文档更新时间: 2025-01-03 14:38   作者:吴长福