alipay.fund.batch.detail.query(批量转账明细查询接口) 在线调试(沙箱环境)

批量转账明细查询接口

公共参数

请求地址

环境HTTPS请求地址
正式环境 https://openapi.alipay.com/gateway.do

公共请求参数

参数 类型 是否必填最大长度描述示例值
app_id String 32 支付宝分配给开发者的应用ID 2014072300007148
method String 128 接口名称 alipay.fund.batch.detail.query
format String 40 仅支持JSON JSON
charset String 10 请求使用的编码格式,如utf-8,gbk,gb2312等 utf-8
sign_type String 10 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 RSA2
sign String 344 商户请求参数的签名串,详见签名 详见示例
timestamp String 19 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" 2014-07-24 03:07:50
version String 3 调用的接口版本,固定为:1.0 1.0
app_auth_token String 40 详见应用授权概述
biz_content String 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

请求参数

参数 类型 是否必填 最大长度 描述 示例值
batch_no String 特殊可选 32 11~32位的数字或字母或数字与字母的组合,且区分大小写。(注:只有境外代发使用,其他场景请使用out_batch_no) hk201703130008
biz_code String 特殊可选 30 批量代发到支付宝账户:BATCH_TRANS_ACC
批量代发到银行账户:BATCH_TRANS_BC
(注:只有境外代发使用,其他场景请使用product_code)
BATCH_TRANS_ACC
biz_scene String 必选 30 批量代发业务场景。如:
GLOBAL: 全球代发. 除CNY的多币种代发或人民币跨境代发。
LOCAL:中国境内纯人民币代发。
MESSAGE_BATCH_PAY:接口报文代发。
GLOBAL
sign_principal String 特殊可选 100 签约主体,即签约了批量代发产品的支付宝账号。
注:境外代发场景下必须传入
test@alipay.com
detail_no String 可选 32 批次文件中明细流水号(注:只有境外代发使用,其他场景请使用out_biz_no) 001
detail_status String 可选 16 境外代发明细状态:
INIT:支付宝只对上传的文件做了记录,还没有处理。
APPLIED:支付宝已完成兑换,等待发起付汇。
DEALED:已发起付汇申请,等待付汇结果。
SUCCESS 处理成功:付汇成功。
FAIL 处理失败:明细信息错误导致明细校验失败或者付汇失败。
DISUSE 已废弃:明细被支付宝系统废弃。

其他场景明细状态:
SUCCESS:成功
FAIL:失败
DEALING:处理中
WAIT_PAY:等待付款
INIT
payee_account String 可选 100 收款方账号。对于批量代发到支付宝账户场景,填写钱包账号。对于批量代发到银行账户场景,填写银行卡号。 zhangsan@alipay.com
page_num Number 可选 3 采用分页查询,本参数为空或0默认显示第一页。(境外代发场景下,每页最大500条记录,不足500条则按实际记录数返回,不需要商户输入每页的记录数。如果输入的值大于总页数,则支付宝返回最后一页数据。
例如:按条件查询到600条数据,则分成2页显示。输入2或大于2的整数都会返回100条数据;不输入任何数据则默认返回第一页,其他场景下,每页大小请输入page_sign字段)。
1
product_code String 特殊可选 64 业务产品码。不同产品值不同,具体值联系支付宝确认。 BATCH_PAY_V2
out_batch_no String 特殊可选 32 商户的批次号 201801310127742502
out_biz_no String 可选 64 商户明细订单号 2018999960760005838333
page_size String 可选 4 每页大小,不传的情况下默认500条,超过500条默认按500条查询;不足500条则按实际记录数返回 1

响应参数

参数 类型 是否必填 最大长度 描述 示例值
batch_trans_id String 必填 18 支付宝系统内部批次请求id。 201801310127742502
batch_no String 选填 32 商户请求的批次流水号,同请求中的"batch_no"。(注:只有境外代发使用,其他场景返回out_batch_no) hk201703130008
biz_code String 选填 30 批量代发业务标识。

批量代发到支付宝账户:BATCH_TRANS_ACC
批量代发到银行账户:BATCH_TRANS_BC
(注:只有境外代发使用,其他场景返回product_code)
BATCH_TRANS_ACC
biz_scene String 必填 30 批量代发业务场景。
如:
GLOBAL:全球代发,多币种代发(包括除人民币以外的同币种代发),需要支付宝做货币兑换。
LOCAL:纯人民币代发,不需要支付宝做货币兑换。
MESSAGE_BATCH_PAY:接口报文代发。
GLOBAL
batch_status String 必填 20 境外场景批次状态:
INIT 批次已接收
WAIT_APPLY 批次资金准备中
DEALING 批次处理中
FINISH 批次处理完成
FAIL 全部处理失败
UNKNOWN 未知状态

其他场景批次状态:
INIT 批次已接收
WAIT_PAY 等待支付
DEALING 批次处理中
SUCCESS 批次处理全部成功
PART_SUCCESS 批次处理部分成功
FAIL 全部处理失败
DISUSE 批次单据废弃
INVALID 批次单据中明细全部无效
INIT
error_code String 选填 100 批次失败错误码.
大部分情况是没有的. 只有余额不足超时关闭或者付款方账户状态不正常
FORCE_DISUSE
fail_reason String 选填 200 批次失败错误原因 批次超时过期作废
sign_principal String 选填 100 签约了批量代发产品的支付宝账号。(注:境外代发场景加会返回) test@alipay.com
payment_amount Price 选填 13 付款方需要支付的金额,受理成功(status为APPLIED)之后才会有值,受理成功之前是0。 13.56
payment_currency String 选填 3 支付币种, 与代发请求的payment_currency相同. USD
page_size Number 必填 4 当前记录数(默认500,达不到500按实际记录返回)。 1
page_num Number 必填 3 当前页数 1
product_code String 选填 64 业务产品码。不同产品值不同,具体值联系支付宝确认。 BATCH_PAY_V2
total_page_count Number 必填 3 总页数 50
out_batch_no String 选填 32 商户的批次号 201801310127742502
gmt_finish String 选填 32 批次处理完成时间 2019-11-08 11:32:11
total_amount String 必填 32 批次总金额 100000
gmt_pay_finish String 选填 32 批次支付完成时间 2019-11-08 11:32:11
payer_id String 选填 32 付款方身份标识 2088302454408770
success_amount String 选填 32 成功金额 100000
fail_amount String 选填 32 失败金额 10000
fail_count Number 选填 4 失败笔数 1000
success_count Number 选填 4 成功笔数 1000
total_item_count Number 必填 4 总记录数 1000
acc_detail_list AccDetailModel 选填 1)当批次状态为INIT状态时,明细信息还未落地,返回明细信息为空
2)如果以上都没有问题,返回明细为空,请检查是否以下情况导致:
1. 校验商户只能查询自己上传的批次信息,批次号不存在或者不是该商户上传的批次。
2. 查询条件没有查询到结果,包括总共5页,商户要求查询第6页的内容。
3. 查询的状态不存在。
detail_no String 特殊可选 32 明细流水号(注:只有境外代发使用,其他场景请使用out_biz_no) 001
payment_amount Price 特殊可选 13 应付金额. 付款方应付金额.
LOCAL场景下为空.
12.3
payment_currency String 特殊可选 3 支付币种.付款方应付的币种, 与批次请求时的payment_currency相同. USD
trans_amount Price 特殊可选 13 转账金额。代发请求中指定的trans_amount. 12.3
trans_currency String 特殊可选 3 转账币种 USD
settlement_amount Price 特殊可选 13 结算金额。
收款方实际收到的金额.
biz_scene是LOCAL场景下,该参数返回空。
81.18
settlement_currency String 特殊可选 3 结算币种.收款方收到的币种. LOCAL场景下为空. CNY
payee_info AccPayeeInfo 必填 100 收款方信息。
payee_account String 必填 100 收款方电子钱包账号。 zhangsan@163.com
payee_name String 必填 140 收款方电子钱包持有者姓名。 张三
cert_info CertInfo 特殊可选 160 收款方身份认证信息。biz_scene=LOCAL时忽略该参数。
cert_no String 特殊可选 128 代发时商家上传的收款方证件号码

biz_scene=LOCAL时忽略该参数。
449559469824905
cert_type String 特殊可选 32 代发时商家上传的收款方证件类型。

biz_scene=LOCAL时忽略该参数。
BUSINESS_LICENSE
remark String 可选 200 备注 ABC
status String 必填 16 INIT:初始
APPLIED:已下单
DEALED:处理中
SUCCESS:处理成功
DISUSE:已废除
FAIL:处理失败
UNKNOWN:未知状态
INIT
exchange_rate ExchangeRate 特殊可选 64 转账币种兑换的汇率信息。biz_scene是LOCAL场景下,该参数返回空。
rate Number 特殊可选 16 转账币种兑换结算币种的汇率。biz_scene是LOCAL场景下,该参数返回空。 6.78
base_currency String 特殊可选 3 兑换汇率的基本币种。biz_scene是LOCAL场景下,该参数返回为空。 USD
exchange_currency String 特殊可选 3 兑换汇率对应的兑换目标币种. LOCAL场景下为空 CNY
need_retry String 可选 1 是否需要通过alipay_order_no原单据重试.
T: 需要;
F或为空: 不需要.
T
alipay_order_no String 可选 64 支付宝订单号 2017031921001004880200287479
out_biz_no String 可选 64 商户明细订单号 2018999960760005838333
detail_id String 可选 32 支付宝系统内部明细单号。 201801310127742532
error_code String 可选 100 明细失败错误码 RECEIVE_ACCOUNT_ERROR
error_msg String 可选 200 明细失败错误原因 收款账户有误或不存在
gmt_create String 可选 64 创建时间 20191120
gmt_finish String 可选 64 完成时间 20191120
sub_status String 可选 64 子状态 DISHONOR

请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayFundBatchDetailQueryRequest request = new AlipayFundBatchDetailQueryRequest();
request.setBizContent("{" +
"\"batch_no\":\"hk201703130008\"," +
"\"biz_code\":\"BATCH_TRANS_ACC\"," +
"\"biz_scene\":\"GLOBAL\"," +
"\"sign_principal\":\"test@alipay.com\"," +
"\"detail_no\":\"001\"," +
"\"detail_status\":\"INIT\"," +
"\"payee_account\":\"zhangsan@alipay.com\"," +
"\"page_num\":1," +
"\"product_code\":\"BATCH_PAY_V2\"," +
"\"out_batch_no\":\"201801310127742502\"," +
"\"out_biz_no\":\"2018999960760005838333\"," +
"\"page_size\":\"1\"" +
"  }");
AlipayFundBatchDetailQueryResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

{
    "alipay_fund_batch_detail_query_response": {
        "code": "10000",
        "msg": "Success",
        "batch_trans_id": "201801310127742502",
        "batch_no": "hk201703130008",
        "biz_code": "BATCH_TRANS_ACC",
        "biz_scene": "GLOBAL",
        "batch_status": "INIT",
        "error_code": "FORCE_DISUSE",
        "fail_reason": "批次超时过期作废",
        "sign_principal": "test@alipay.com",
        "payment_amount": 13.56,
        "payment_currency": "USD",
        "page_size": 1,
        "page_num": 1,
        "product_code": "BATCH_PAY_V2",
        "total_page_count": 50,
        "out_batch_no": "201801310127742502",
        "gmt_finish": "2019-11-08 11:32:11",
        "total_amount": "100000",
        "gmt_pay_finish": "2019-11-08 11:32:11",
        "payer_id": "2088302454408770",
        "success_amount": "100000",
        "fail_amount": "10000",
        "fail_count": 1000,
        "success_count": 1000,
        "total_item_count": 1000,
        "acc_detail_list": [
            {
                "detail_no": "001",
                "payment_amount": 12.3,
                "payment_currency": "USD",
                "trans_amount": 12.3,
                "trans_currency": "USD",
                "settlement_amount": 81.18,
                "settlement_currency": "CNY",
                "payee_info": {
                    "payee_account": "zhangsan@163.com",
                    "payee_name": "张三"
                },
                "cert_info": {
                    "cert_no": "449559469824905",
                    "cert_type": "BUSINESS_LICENSE"
                },
                "remark": "ABC",
                "status": "INIT",
                "exchange_rate": {
                    "rate": 6.78,
                    "base_currency": "USD",
                    "exchange_currency": "CNY"
                },
                "need_retry": "T",
                "alipay_order_no": "2017031921001004880200287479",
                "out_biz_no": "2018999960760005838333",
                "detail_id": "201801310127742532",
                "error_code": "RECEIVE_ACCOUNT_ERROR",
                "error_msg": "收款账户有误或不存在",
                "gmt_create": "20191120",
                "gmt_finish": "20191120",
                "sub_status": "DISHONOR"
            }
        ]
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

异常示例

{
    "alipay_fund_batch_detail_query_response": {
        "code": "20000",
        "msg": "Service Currently Unavailable",
        "sub_code": "isp.unknow-error",
        "sub_msg": "系统繁忙"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

业务错误码

公共错误码

错误码错误描述解决方案
MAX_VISIT_LIMIT 超出最大访问限制 请稍后重试。
ILLEGAL_ARGUMENT 请求参数有误或格式不正确 检查查询请求参数的合法性
NO_SIGN_PRODUCT 产品未签约或已失效 查询接口有效但对应的代发产品没有权限,或者协议已经失效,请检查合约是否生效
USER_NOT_EXIST 付款方用户信息不存在 sign_principal用户信息不存在
PARTNER_NOT_MATCH 暂不支持付款账户与签约账户不一致的场景 如果biz_scene是GLOBAL场景,接口请求方(app_id)必须和代发文件中付款方保持一致; 如果biz_scene是LOCAL场景,payer_principal必须和代发文件中付款方保持一致;
BATCH_NOT_EXIST 批次信息不存在 请检查批次号是否正确
NO_PERMISSION 报错,无权限查询该批次信息 查询的批次信息不是该商家上传的批次
UN_SUPPORT_QUERY 查询的明细信息不存在 接口暂时不支持该类代发产品查询
SYSTEM_ERROR 系统繁忙 如重试后仍然系统异常,请及时联系支付宝技术服务人员
RESOURCE_LIMIT_EXCEED 请求超过资源限制 请求并发数超过支付宝处理速度,请降低请求并发数
FORCE_DISUSE 终止支付,关闭订单 已关单,无法操作
onlineServer