Download Settlement File

This API allows merchants to download settlement files containing detailed transaction information and settlement data.

Permission Required

Before calling this API, please contact Onerway to obtain download permission.

API Request Parameters

GET

Header

Important Notes

Please add the following parameters to the request header, not in the request path

• Note that the date format is yyyyMMdd, like 20211026, not 2021-10-26
• This API returns a file stream with Content-Type: application/octet-stream in the response header
• Only UTF-8 character set is supported
• We recommend writing the file stream to a file with a .csv extension

Parameter	Type	Length	Required	Signed	Description
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway, obtained from Onerway dashboard
date	String	8	Yes	Yes	Settlement date. Format: yyyyMMdd
currency	String	8	Yes	Yes	Settlement currency. See ISO 4217
sign	String	/	Yes	No	Digital signature string for request verification. Please refer to Signature for signature generation method.

Response

The API returns a file stream containing settlement data in CSV format.

Settlement Batch Information

Field Name	Description
Settlement Date	Settlement date calculated based on settlement cycle
Settlement Currency	The currency used for merchant settlement
Transaction Amount	Transaction amount in settlement currency
Refund Amount	Amount of successful refund transactions
Transaction Processing Fee	Processing fee charged for payment transactions
Refund Processing Fee	Processing fee charged for refund transactions
Fee	Transaction fee charged 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, to be returned upon maturity
Settlement Amount	Settlement amount, net amount after transaction amount and fee offset
Platform fee	Platform fee
Fraud Administration Fee	Fraud management fee
Decision management Fee	Risk decision management fee

Settlement Details

Field Name	Description
Settlement Date	Settlement date calculated 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 status
Settlement Currency	The 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, to be returned upon maturity
Settlement Amount	Settlement amount per transaction, net amount after transaction amount and fee offset
Settlement Status	Settlement status, success/failure
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

Transaction Types

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.

Integration Process

The settlement file download process consists of a simple request-response flow:

In this process:

• Merchant system sends a GET request with proper header parameters
• Onerway processes the request and generates the settlement file
• Onerway returns the file as a stream in the response
• Merchant system saves the file stream to a CSV file for further processing

API Usage Examples

Download Settlement File

Use this method to download settlement files for a specific date and currency:

Java Example

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");
        get.setRequestHeader("date", "20211026");
        get.setRequestHeader("currency", "USD");
        get.setRequestHeader("sign","...");
        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) {
            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);
        }
        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);
    }
}

Common Error Scenarios and Solutions

Scenario 1: Permission Access Issues

If you receive a permission denied error:

• Ensure your merchant account has been granted settlement file download permissions
• Verify your merchant number is correctly configured in the request header
• Check with Onerway support team to confirm permission status

Scenario 2: Empty File

If you receive an empty file or a file with no data:

• Verify the signature is correct - incorrect signatures can cause authentication failures
• Check if settlement data exists for the requested currency - not all currencies may have settlement data for every day
• Confirm the requested date has settlement files available - settlement files may not be generated for dates with no transaction activity

Implementation Best Practices

1. Scheduled Downloads: Set up automated scheduled jobs to download settlement files daily for reconciliation

2. File Naming Convention: Use a consistent naming convention for saved files, such as settlement_YYYYMMDD_CURRENCY.csv

3. Retry Mechanism: Implement a retry mechanism with exponential backoff for network failures

4. Validation Process: Validate downloaded files to ensure they contain the expected data before processing

5. Archive Strategy: Establish a file archiving strategy for historical settlement data

6. Reconciliation Process: Develop an automated reconciliation process to match settlement data with your transaction records

7. Error Handling: Implement comprehensive error handling for API calls, file saving, and file processing

8. Security Considerations: Store settlement files securely and limit access to authorized personnel only

Merchant Integration Checklist

Before implementing the Settlement File Download API in your production environment, ensure you have:

• Obtained settlement file download permission from Onerway
• Proper signature generation implementation
• Automated download mechanism for daily/periodic downloads
• File storage and archiving solution
• CSV parsing capability for processing the settlement data
• Reconciliation system for matching settlement data with transaction records
• Security measures for handling sensitive settlement data
• Alert system for download failures or discrepancies
• Testing completed in sandbox environment
• Documentation of your settlement file processing workflow

Sample Settlement File

You can download a sample settlement file here to understand the format before implementing the API.