下载结算文件

此API允许商户下载包含详细交易信息和结算数据的结算文件。

权限要求

调用此API前，请联系Onerway获取下载权限。

API请求参数

GET

Header

重要说明

请将以下参数添加到请求头中，不要添加到请求路径中

• 注意日期格式为yyyyMMdd，如20211026，不是2021-10-26
• 此API返回文件流，响应头中Content-Type: application/octet-stream
• 仅支持UTF-8字符集
• 建议将文件流写入扩展名为.csv的文件中

Parameter	Type	Length	Required	Signed	Description
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway upon registration, obtained from the Onerway merchant dashboard.
date	String	8	Yes	Yes	Settlement date for transaction processing.
currency	String	8	Yes	Yes	Settlement currency for transaction processing. See ISO 4217 for complete list.
sign	String	/	Yes	No	Digital signature string for request verification and security. Please refer to Signature for signature generation method.

响应

此API返回包含CSV格式结算数据的文件流。

结算批次信息

Field Name	Description
Settlement Date	Settlement date based on settlement cycle
Settlement Currency	Currency used for merchant settlement
Transaction Amount	Transaction amount in settlement currency
Refund Amount	Amount of successful refund transactions
Transaction Processing Fee	Processing fee for payment transactions
Refund Processing Fee	Processing fee for refund transactions
Fee	Transaction fee for payment transactions
Interchange Fee	Only present in IC++ mode
Scheme Fee	Only present in IC++ mode
Markup	Only present in IC++ mode
Deposit Release	Amount of returned deposit
Deposit	Deposit amount, returned upon maturity
Settlement Amount	Net settlement amount after transaction amount and fee offset
Platform fee	Platform fee
Fraud Administration Fee	Fraud management fee
Decision management Fee	Risk decision management fee

结算明细

用于结算和报告目的

Field Name	Description
Settlement Date	Settlement date based on settlement cycle
Settlement Batch ID	Settlement batch number, one batch ID per settlement batch
Transaction ID	Transaction order number
Merchant Order ID	Merchant transaction order number
Production Type	Product type
Card Type	Card type or local payment method
APP ID	Merchant application ID. Created by Onerway when merchant registers a website
Transaction URL	Merchant transaction website
Order_Currency	Transaction order currency
Order Amount	Transaction order amount
Transaction Type	Transaction type. Please refer to TransactionTypes
Transaction Status	Transaction processing status. Please refer to TxnStatusEnum
Settlement Currency	Currency used for merchant settlement
Transaction Amount	Transaction amount in settlement currency
Processing Fee	Processing fee
Fee	Transaction fee
Interchange Fee	Only present in IC++ mode
Scheme Fee	Only present in IC++ mode
Markup	Only present in IC++ mode
Deposit	Deposit amount, returned upon maturity
Settlement Amount	Net settlement amount per transaction after transaction amount and fee offset
Settlement Status	Settlement payout status indicating the fund disbursement result. Please refer to SettlementStatusEnum
Wallet Type Code	Wallet type code (currently only has value when local payment method is Alipay+)
Merchant Order Time	Time when merchant transaction order occurred
Platform type	Platform type
Platform fee	Platform fee
Fraud Administration Fee	Fraud management fee
Decision management Fee	Risk decision management fee
Fee Percentage	Fee percentage
Markup Fixed amount	Markup fixed amount
Markup Fixed currency	Markup fixed currency
Markup Percentage	Markup percentage
Transaction complete time	Transaction completion time
card product	Card type
card category	Card category

交易类型

Code	Description
SALE	Payment transaction. Standard transaction for purchasing goods or services.
REFUND	Refund transaction. Reverses a previous payment transaction, returning funds to the customer.
CB	Chargeback transaction. Initiated when a customer disputes a transaction with their card issuer.
CB_CANCEL	Chargeback cancellation transaction. Cancellation of a previously initiated chargeback.
CB_VOID	Chargeback void. Voids a chargeback that was previously initiated.
CB_APPEAL	Chargeback first appeal. First appeal submitted by merchant against a chargeback.
CB_APPEAL_SUCCESS	Chargeback first appeal success. First appeal was successful and chargeback was reversed.
CB_APPEAL_SECOND	Chargeback second appeal. Second appeal submitted by merchant after first appeal rejection.
CB_APPEAL_SECOND_SUCCESS	Chargeback second appeal success. Second appeal was successful and chargeback was reversed.
CB_APPEAL_SECOND_FAILURE	Chargeback second appeal failure. Second appeal was rejected and chargeback stands.

集成流程

结算文件下载流程包含简单的请求-响应流程：

此流程中：

• 商户系统发送带有正确头部参数的GET请求
• Onerway处理请求并生成结算文件
• Onerway在响应中返回文件流
• 商户系统将文件流保存为CSV文件以供进一步处理

API使用示例

下载结算文件

使用此方法下载特定日期和币种的结算文件：

Java示例

public void downLoad(@RequestParam("localFileName") String localFileName, HttpServletResponse response) {
    HttpClient client = new HttpClient();
    GetMethod get = null;
    FileOutputStream output = null;
    try {
        get = new GetMethod("https://sandbox-acq.onerway.com/v1/settlementFile/download");
        get.setRequestHeader("merchantNo", "500010");        // [!code focus] // 商户号，从控制台获取
        get.setRequestHeader("date", "20211026");            // [!code focus] // 结算日期，格式yyyyMMdd
        get.setRequestHeader("currency", "USD");             // [!code focus] // 结算币种
        get.setRequestHeader("sign","...");                  // [!code warning] // 签名，使用所有参数生成
        MultiThreadedHttpConnectionManager connectionManager = new MultiThreadedHttpConnectionManager();
        HttpConnectionManagerParams params = new HttpConnectionManagerParams();
        params.setConnectionTimeout( 20000 );
        params.setSoTimeout( 20000 );
        connectionManager.setParams(params);
        client = new HttpClient(connectionManager);
        HttpClientParams clientParams = new HttpClientParams();
        clientParams.setParameter("http.protocol.allow-circular-redirects", true);
        clientParams.setParameter("http.protocol.max-redirects", 4);
        client.setParams(clientParams);
        int i = client.executeMethod(get);
        if (200 == i) {                                      // [!code focus] // 检查响应状态
            File storeFile = new File(localFileName);
            output = new FileOutputStream(storeFile);
            output.write(get.getResponseBody());
        } else {
            System.out.println("DownLoad file occurs exception, the error code is :" + i); // [!code error] // 错误处理
        }
        InputStream inStream = new FileInputStream(localFileName);
        response.reset();
        response.setContentType("application/octet-stream");
        response.addHeader("Content-Disposition", "attachment; filename=\"" + localFileName + "\"");
        byte[] b = new byte[100];
        int len;
        try {
            while ((len = inStream.read(b)) > 0)
                response.getOutputStream().write(b, 0, len);
            inStream.close();
        } catch (IOException e) {
            e.printStackTrace();
        }
    } catch (Exception e) {
        e.printStackTrace();
    } finally {
        try {
            if(output != null){
                output.close();
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
        get.releaseConnection();
        client.getHttpConnectionManager().closeIdleConnections(0);
    }
}

常见错误场景及解决方案

场景1：权限访问问题

如果收到权限被拒绝的错误：

• 确保您的商户账户已被授予结算文件下载权限
• 验证请求头中的商户号配置正确
• 联系Onerway支持团队确认权限状态

场景2：空文件

如果收到空文件或无数据的文件：

• 验证签名是否正确 - 错误的签名可能导致认证失败
• 检查请求的币种是否有结算数据 - 并非所有币种每天都有结算数据
• 确认请求的日期是否有结算文件 - 没有交易活动的日期可能不会生成结算文件

实施最佳实践

1. 定时下载：设置自动化定时任务，每日下载结算文件进行对账

2. 文件命名规范：使用一致的命名规范保存文件，如settlement_YYYYMMDD_CURRENCY.csv

3. 重试机制：为网络故障实施指数退避的重试机制

4. 验证流程：在处理前验证下载的文件包含预期数据

5. 存档策略：为历史结算数据建立文件存档策略

6. 对账流程：开发自动化对账流程，将结算数据与交易记录匹配

7. 错误处理：为API调用、文件保存和文件处理实施完善的错误处理

8. 安全考虑：安全存储结算文件，仅限授权人员访问

商户集成检查清单

在生产环境中实施结算文件下载API之前，请确保您已：

• 从Onerway获得结算文件下载权限
• 正确的签名生成实现
• 每日/定期下载的自动化机制
• 文件存储和存档解决方案
• 处理结算数据的CSV解析能力
• 将结算数据与交易记录匹配的对账系统
• 处理敏感结算数据的安全措施
• 下载失败或差异的警报系统
• 在沙箱环境中完成测试
• 结算文件处理工作流程的文档记录

结算文件示例

您可以在此处下载结算文件示例，以便在实施API之前了解格式。