很多我们客户的老板和财务对资金的具体流程以及细分流水表现额外的关注。那么小编今天就来介绍一下我们牛卡派产品中的对账功能。(有需求的可以看我的主页加好友私信哦~)
对账单
1. 产品介绍
1.1 简介
我们的系统提供交易对账文件的生成配置及下载功能。包括交易、结算、分账类型的对账文件。交易、结算对账文件支持按日或按月跑批生成。
1.2 应用场景
- 渠道商、连锁、集团企业、平台类商户查询下载下属商户的交易、结算、分账对账文件;
- 商户下载自己的交易、结算、分账对账文件;
- 渠道、商户为下属用户下载结算、对账文件;
2. 接入前准备
2.1 商务准备
商户可以在控台上配置对账文件的生成。
支持商户控台下载对账文件:
渠道商控台下载对账文件操作如下:
1) 渠道商控台:交易结算->对账单下载; 选择产品、选择需下载的文件类型,选择文件日期(对账单T+1日生成,如需要2月8日的交易对账单,文件日期请填写2月9日)
2) 查询出文件后,点击“下载”根据提示需要打开文件/保存文件。
也支持接口配置对账文件生成与下载。
2.2 对接准备
第一步:密钥获取
联调之前需要先获取公私钥
第二步:公共参数获取
登录服务商/商户控台后,可在开发设置-开发者信息中,获取sys_id,product_id参数信息;
3. 开发指引
3.1 对接规范
调用接口,均采取POST形式提交,数据格式统一为JSON格式。
3.2 系统接口
3.2.1 交易结算对账单配置
入参需关注以下域字段:
参数 | 中文名 | 说明 |
---|---|---|
recon_send_flag | 对账文件生成开关 | Y:是 N:否;示例值:Y |
file_type | 对账单类型 | 选择需要生成的对账单类型 |
include_data_range | 包含数据范围 | 对账单是否包含用户数据 |
3.2.2 交易结算对账单重新生成
该接口用于重新生成指定日期的对账文件;入参关注以下字段:
参数 | 中文名 | 说明 |
XXX_id | 支付机构编号 | 渠道商编号/代理商编号/商户编号; |
file_type | 对账单类型 | 选择需要生成的对账单类型 |
返参需关注以下域字段:
参数 | 中文名 | 说明 |
file_type | 对账单类型 | 生成的对账单类型 |
download_url | 文件下载地址 | 如果为空请调用【交易结算文件查询】接口获取下载地址; |
3.2.3 交易结算对账单查询
获取已生成的对账文件的下载地址;入参关注以下字段:
参数 | 中文名 | 说明 |
file_date | 文件生成日期 | 指定文件日期 |
file_type | 对账单类型 | 选择需要生成的对账单类型 |
返参需关注以下域字段:
参数 | 中文名 | 说明 |
file_details | 文件信息 | jsonObject字符串 |
4.API接口
很多技术人员向小编反馈,说只有一些接口名称,没有相关接口代码。那么,为了解决这一问题,我们牛卡派技术团队将简要的展示部分接口代码,来方便广大客户看到技术对接的难易程度。
API接口列表
类型 | 功能 | 描述 |
API | 交易结算对账文件配置 | 对账文件配置 |
API | 交易结算对账单配置查询 | 查询对账文件配置 |
API | 交易结算对账文件重新生成 | 重新生成指定日期的对账文件 |
API | 交易结算对账单查询 | 获取对账文件下载地址 |
4.1交易结算对账文件配置
应用场景
调用本接口实现对账文件定期生成,同时支持推送到指定的SFTP服务器上。
适用对象
需要交易、结算对账的渠道商、商户。渠道商、商户支持账单类型如下:
- 渠道商:日结算对账单、日分账对账单、日出金对账单、日交易数据、月结算对账单、月交易数据。
- 商户:日结算对账单、日分账对账单、日出金对账单、日用户结算对账单、日交易数据、月结算对账单、月交易数据。
公共参数
- 公共请求参数
参数 | 中文名 | 定义 | 长度 | 必填 | 说明 |
sys_id | 系统号 | String | 32 | Y | 渠道商/商户的XXX_id |
product_id | 产品号 | String | 32 | Y | 三方机构分配的产品号,示例值:YYYY |
sign | 加签结果 | String | 512 | Y | 签名,对报文整体签名 |
data | 请求数据 | JSON | Y | 业务请求参数 |
- 公共返回参数
参数 | 中文名 | 定义 | 长度 | 必填 | 说明 |
sign | 签名 | String | 512 | Y | 签名,对报文整体签名 |
data | 响应内容体 | JSON | N | 业务返回参数 |
请求参数
data
参数 | 中文名 | 定义 | 长度 | 必填 | 说明 |
req_date | 请求日期 | String | 8 | Y | 请求格式:yyyyMMdd;示例值:2024723 |
req_seq_id | 请求流水号 | String | 128 | Y | 同一XXX_id下当天唯一;示例值:rQ2023121311173944 |
XXX_id | 三方机构编号 | String | 32 | Y | 渠道商编号/商户编号; |
recon_send_flag | 对账文件生成开关 | String | 1 | Y | Y:是 N:否;示例值:Y |
ftp_addr | SFTP地址 | String | 64 | N | |
ftp_user | SFTP用户名 | String | 32 | N | 示例值:test |
ftp_pwd | SFTP密码 | String | 64 | N | 示例值:test |
file_type | 对账单类型 | String | 8 | Y | 对账文件生成开关=“Y”时必填; |
as_settle_flag | 是否跟随结算时间 | String | 1 | N | Y:是N:否。仅对渠道商生效,配置后所属商户对账单按结算时间生成;示例值:Y |
notify_url | 跑批完成通知地址 | String | 200 | N | 跑批完成通知地址。仅当as_settle_flag为是时起作用。 |
contain_user | 用户数据范围 | String | 1 | N | 包含用户数据范围。0:不包含用户(默认),1:包含商户下用户的数据;服务商默认包含直属用户数据;示例值:1 |
contain_merchant | 商户数据范围 | String | 1 | N | 包含商户数据范围。0:直属商户(默认),1:全量商户;示例值:1 |
请求示例
{
"sys_id": "66660000000000000",
"product_id": "YYYY",
"data": {
"req_seq_id": "20240723162935106kciqg4z5ff48hl",
"file_type": "1,2,3,4",
"req_date": "20240723",
"XXX_id": "66660000000000000",
"recon_send_flag": "Y"
},
"sign": "bf9gBitgd64j38rQ6H+6hMxubRhm0LXW/uyQ44wj4OO5eBLHT83cIf/RqQFOj2AKzlwo3CiQ+rBUG0/nE9yznRJX93dmfMKfRE0nxZSlaALLptQyW+TfM42gsEVxaZMnwmDhq5gyvYXgprRVE2tzoFF3Jj6fZvJvKPnA8UfPmiynQKZZVsmOOn3ISvMHfK1EJ346fLrDeQPP+IoQYq4USFMYehMFQWXna8XcYeJNjg3qY7IYT4Z4/FET43bcRNbUwnErvn5nxzQDqtObTzmr3Uf9U7in7cCYWddSxq1k3drSW20TGZTlGfdpK1T/DJ5uK4yTPIi5wlYLNmSEfcO7aQ=="
}
返回参数
同步返回参数
data
参数 | 中文名 | 定义 | 长度 | 必填 | 说明 |
resp_code | 返回码 | String | 8 | Y | 成功:00000000 ;审核中:90000000 ;其他失败;示例值:00000000 |
resp_desc | 返回描述 | String | 512 | N | 业务响应信息;示例值:成功 |
req_seq_id | 请求流水号 | String | 32 | Y | 示例值:534928202208231442312603150 |
req_date | 请求日期 | String | 8 | Y | 格式:yyyyMMdd,示例值:20240723 |
XXX_id | 三方机构编号 | String | 18 | Y | 渠道商编号/商户编号;示例值:6666000000000000 |
recon_send_flag | 对账文件生成开关 | String | 1 | Y | Y:是 N:否;示例值:Y |
ftp_addr | SFTP地址 | String | 64 | N | |
ftp_user | SFTP用户名 | String | 32 | N | 示例值:test |
file_type | 对账单类型 | String | 8 | N | 对账文件生成开关=“Y”时必填; |
as_settle_flag | 是否跟随结算时间 | String | 1 | N | Y:是N:否。仅对渠道商生效,配置后所属商户对账单按结算时间生成;示例值:Y |
notify_url | 跑批完成通知地址 | String | 200 | N | 跑批完成通知地址。 |
contain_user | 用户数据范围 | String | 1 | N | 包含用户数据范围。0:不包含用户(默认),1:包含商户下用户的数据;服务商默认包含直属用户数据;示例值:1 |
contain_merchant | 商户数据范围 | String | 1 | N | 包含商户数据范围。0:直属商户(默认),1:全量商户;示例值:1 |
返回报文案例
{
"data":{
"resp_code":"00000000",
"resp_desc":"成功",
"req_seq_id":"rQ2024072308451565534417022830",
"req_date":"20220527",
"XXX_id":"6666000000000000",
"recon_send_flag":"Y",
"ftp_user":"ubmpc_test",
"ftp_addr":"ftp://192.168.16.171:22/app/ubmpc_test/ubmpc",
"file_type":"1,2,3,4"
}
}
4.2交易对账结算单查询
相关接口场景与适用场景同上方一致。
公共参数
- 公共请求参数
参数 | 中文名 | 定义 | 长度 | 必填 | 说明 |
sys_id | 系统号 | String | 32 | Y | 渠道商/商户的XXX_id |
sign | 加签结果 | String | 512 | Y | 签名,对报文整体签名 |
product_id | 产品号 | String | 32 | Y | 支付机构分配的产品号,示例值:MCS |
data | 数据 | String | Y | JSON格式 |
请求参数
data
参数 | 中文名 | 定义 | 长度 | 必填 | 说明 |
req_date | 请求日期 | String | 8 | Y | 格式:yyyyMMdd,示例值:20240723 |
req_seq_id | 请求流水号 | String | 128 | Y | 请求流水号,示例值:2024072308126665001 |
XXX_id | 三方客户Id | String | 18 | Y | 渠道与一级代理商的直属商户ID;示例值:6666000000000000 |
file_date | 文件生成日期 | String | 8 | Y | 格式:yyyyMMdd,示例值:20240723; |
file_type_query | 文件类型 | String | 1 | N | 1、日对账单,包括日结算对账单、日分账对账单、日出金对账单 |
请求示例
{
"sys_id": "6666000000000000",
"product_id": "YYYY",
"data": {
"file_date": "20240723",
"file_type_query": "2",
"req_seq_id": "20240506094347392bzgooscof4vgn0",
"req_date": "20240723",
"XXX_id": "6666000000000000"
},
"sign": "gUwoKu+SSer6fk/q0A7YFCFVhGjuKjxV+XabE3aennoxxBB+1i7T3AELEvVVstYypUM6kFSmpB4+jrhV3RCgRAfNHVuEH/emVHpF1wDPRTrco27Y1XuEhOviGDPKXRSZpLOXOvN+9xqqnPE+XDVr5Xnr4t31nLWlokgFx4mfTI/2HvCcFu3pY+Km4gYy7S7u4CbLG+BkQHrKAGneI5ZAspFWWNBOYbxb+lx7F6X56pjL/VM7DrNaNcWAvAszT12XyL53kySYrM4GWJKD4Ycwrp8761oRZB/qJFv8LAzd/PKU/4M+oZHBmxgM4RX/l8WbknnEvZoue9CCc1bDX8ED4w=="
}
返回参数
data
参数 | 中文名 | 定义 | 长度 | 必填 | 说明 |
resp_code | 业务返回码 | String | 8 | Y | 业务返回码;示例值:00000000 |
resp_desc | 业务返回描述 | String | 512 | Y | 业务返回码;示例值:成功 |
req_date | 请求日期 | String | 8 | Y | 原请求信息返回;示例值:20240723 |
req_seq_id | 请求流水号 | String | 128 | Y | 原请求信息返回;示例值:20221107163916760m1lqvgmjmxw8fm |
file_details | 文件信息 | jsonArray | N | 文件生成才会有值 | |
task_details | 文件生成任务信息 | jsonArray | N | 可以查看还未生成的文件,包含生成文件跑批任务的状态信息 |
响应示例
{
"data":{
"resp_code":"00000000",
"resp_desc":"查询成功",
"file_details":[
{
"download_url":"https://file.cloudpnr.com/app-86820a0f-8b13-479b-a466-b261af7290d5%2Fsaturnfile%2F60bdb3fcbe534c25ab80c908578a0c59%2F1161cd50-31e9-11ee-9bd1-0242ac110002.zip?Signature=EIqOPgBSjwS7Iy3UvYQiZYgDm8g%3D&OSSAccessKeyId=LTAI6Yzq9tIYS57h&Expires=1722671156",
"file_date":"20240723",
"file_id":"f577ea48-033b-3f08-8ae5-994ec0996053",
"file_Name":"20240723_6666000111546360_order.zip",
"file_type":"3",
"XXX_id":"6666000000000000",
"time_type":""
}
],
"task_details":[
{
"data_date":"20240723",
"download_url":"https://file.cloudpnr.com/app-86820a0f-8b13-479b-a466-b261af7290d5%2Fsaturnfile%2F60bdb3fcbe534c25ab80c908578a0c59%2F1161cd50-31e9-11ee-9bd1-0242ac110002.zip?Expires=1722671156&OSSAccessKeyId=LTAI6Yzq9tIYS57h&Signature=EIqOPgBSjwS7Iy3UvYQiZYgDm8g%3D",
"file_id":"f577ea48-033b-3f08-8ae5-994ec0996053",
"file_name":"20240723_6666000111546360_order.zip",
"file_type":"3",
"XXX_id":"6666000000000000",
"task_end_time":"20240723183238",
"task_start_time":"20240723183237",
"task_stat":"S"
}
]
},
"sign":"fy2NgWhzpKQeoLL6PIv4DeXvAWHWa1ezw7H5EaIm5RhyM3MjzqHThhRoJLfz1xpFh4aDW4T5MQSYz4//es0aHD6OA+ZHO3xZWy8MAxArWHPVHe6ksylRju5nKjCMSAe3ath711twdejcatcm8Fc4Ollaeg1cYmUdA3d79ct5hGTsAQ2ewqRGG5wBUt9X6m0Q8GTnReTgm938B3kHU8RlVQXHf/TGHK8xcMIs5WTH/bRgfbFfvuNrRP8uaKao0q7mmZfVw6NzDzXpTYaTc3p1auYijc2oqo43y3dERSggKV5Z5uQCvbDIfd7hydG2rrLdGppcv51yQmInkIKDu8cmoQ=="
}