Reconciliation Files & Specifications
    • Overview
    • Reconciliation Files
      • File-01 Activity_Detail Online Transaction Detail File
      • File-02 Settlement_Detail Settlement Transaction Detail File
      • File-03 Miscellaneous_Detail Manual Settlement Transaction Detail File
      • File-04 PSP_Reconciliation_Detail PSP Settlement Reconciliation Transaction Detail File
      • File-05 PSP_Miscellaneous_Detail PSP Settlement Exception and Special Transaction Detail File
      • File-06 Interchange_Scheme_Fee_Detail Interchange and Scheme Fee Detail File
      • File-07 PSP_Interchange_Scheme_Fee_Detail PSP Interchange and Scheme Fee Detail File
      • File-08 Network_Token_Cryptogram_Detail Network Token Cryptogram Detail File
    • Card BIN File
      • BIN File

    Overview

    Evo Payment clearing and settlement system provides batch reconciliation transaction file data to help integrating parties perform internal clearing and reconciliation operations such as internal transaction data matching, exception handling, and PSP reconciliation. Integrating parties can download reconciliation data through the Evo Payment G2 service platform or obtain it via SFTP, and use it to complete automated reconciliation and daily operational checks.

    Basic concepts#

    This section introduces the basic concepts used in the Evo Payment reconciliation documentation.

    Transaction detail data file#

    A transaction detail data file is a data-format file for processing by integrating-party systems. It is mainly used by integrating parties for automated transaction matching and automated reconciliation processing within their internal systems. At the daily cut-off time point, the file is produced for all online transaction record details within the previous natural day's daily cut-off cycle, and includes all transaction types under all transaction statuses (including failed-status transactions).
    Note : If a Merchant had no online transactions on the previous day, Evo Payment still produces an empty file, retaining only the field names and the end marker (***END***).

    Reconciliation report data file#

    A reconciliation report data file is a readable report file for daily reconciliation by integrating-party operations personnel. It is mainly used for daily data checks by integrating-party operations, disputes, exceptions, and other functions.

    Card BIN file#

    In addition to transaction details and reconciliation reports, Evo Payment also supports obtaining Card BIN files for integrating parties to query and use in scenarios such as risk control, routing, and exchange rates.

    File hierarchy#

    Based on Evo Payment system configuration, reconciliation files can be produced with detail data at different dimensions according to the following hierarchies:
    1.
    Acquirer level (Acquirer)
    2.
    Group level (Group)
    3.
    Merchant level (Merchant)
    4.
    Store level (Store)

    Cycle#

    Evo Payment clearing and settlement system uses the natural day as the basic reconciliation cycle. Corresponding daily cut-off reconciliation files are produced every Monday through Sunday and generated daily from 10:00–12:00 AM (Evo Payment node system time).

    Reconciliation files#

    This section provides the list, generation time, and download methods for Evo Payment reconciliation files.

    Reconciliation file list and reconciliation purposes#

    Evo Payment reconciliation files include transaction detail data files and reconciliation report data files. The following table describes the purpose of each file:
    Transaction detail data files
    NameDescriptionPurpose
    File-01 Activity_Detail Online Transaction Detail FileDetail data for all online transaction records within the integrating party's business cycle, produced at the daily cut-off time pointUsed by the integrating party's system to match its own orders one by one by Merchant transaction ID or Evo Payment transaction ID, check transaction amount, currency, exchange rate, transaction status, and system/PSP response code information, and associate subsequent transactions such as refunds and cancellations through the original transaction ID, serving as baseline data for automated transaction matching and automated reconciliation
    File-02 Settlement_Detail Settlement Transaction Detail FileDetail data for records participating in settlement within the integrating party's business cycle, produced at the daily cut-off time pointUsed to check the transaction amount, settlement amount and settlement currency, settlement exchange rate, as well as MDR charging rules and fees, IC fees, card scheme fees, acquiring service fees, value-added tax/withholding tax, and other fees for each transaction participating in settlement within the settlement cycle, and the Merchant settlement net amount, thereby confirming Merchant settlement posting
    File-03 Miscellaneous_Detail Settlement Manual Transaction Detail FileDetail data for manual or special settlement transaction records participating in settlement within the integrating party's business cycle, produced at the daily cut-off time pointUsed to check non-transaction records and manually initiated special settlement records within the settlement cycle, locate their sources based on record date, record type, record reason code, and record reference number, and check the impact of their settlement amount, fees, taxes, and settlement net amount on Merchant settlement
    File-04 PSP_Reconciliation Detail PSP Settlement Reconciliation Transaction Detail FileDetail data for records successfully matched between PSP settlement and the Evo Payment system within the integrating party's business cycle, produced at the daily cut-off time pointUsed for transaction-by-transaction matching with PSP settlement data, checking each transaction's PSP settlement date, settlement amount and currency, settlement exchange rate, discount amount, IC fee, value-added tax/withholding tax, and settlement net amount, and confirming that PSP-side posting is consistent with system accounting
    File-05 PSP_Miscellaneous_Detail PSP Settlement Exception and Special Transaction Detail FileDetail data for exceptions and special settlement transaction records in PSP settlement within the integrating party's business cycle, produced at the daily cut-off time pointUsed to check exception records that could not be normally matched in PSP settlement and special settlement records such as disputes and adjustments, and to perform exception handling and dispute checks based on record type, record reason code, and record reference number
    File-06 Interchange_Scheme_Fee_Detail IC Fee and Scheme Fee Detail FileVisa and Mastercard Interchange fee and card scheme fee data within the integrating party's business cycle, produced at the daily cut-off time pointUsed to check the Interchange fee and Scheme fee calculated by Evo Payment transaction by transaction, validate whether the fee item name, fee code, and charging rule are applied correctly, and support transaction cost accounting and Merchant pricing review
    File-07 PSP_Interchange_Scheme_Fee_Detail PSP IC Fee and Scheme Fee Detail FileInterchange fee and card scheme fee data for Visa and Mastercard PSP settlement within the integrating party's business cycle, produced at the daily cut-off time pointUsed to compare the Interchange fee and Scheme fee returned by PSP settlement with the Evo Payment calculation results (File-06) transaction by transaction, and check PSP charging rules and fee differences
    File-08 Network_Token_Cryptogram_Detail Network Token Cryptogram Detail FileDetail data within the integrating party's business cycle for cryptograms generated by Cryptogram and used for Network Token payments, produced at the daily cut-off time pointUsed to check transactions completed through Network Token and Cryptogram, match the correspondence between tokens and cards based on token number, token unique reference number, payment account reference (PAR), authentication type, and authentication identifier, and support token transaction reconciliation and issue troubleshooting
    Note :
    All files uniformly use UTF-8 with BOM encoding;
    Files are provided in CSV format, and the field delimiter is "," (double quotation mark + English comma);
    File content uses the newline character \n (0x0A) as the line ending;
    The last line of the file content uses ***END*** as the content end marker;

    Reconciliation file download#

    Integrating parties can obtain reconciliation files in the following two ways:

    Evo Payment service platform#

    Integrating parties can log in to the Evo Payment service platform to download reconciliation files directly.

    SFTP#

    Default directory: Evo Payment serves as the SFTP Server, with the address /in/{YYYYMMDD};
    Login method: public/private key authentication;
    Transfer completion marker: After Evo Payment finishes transferring a file to the SFTP directory, it additionally generates an empty TXT text-format file with the same name as the reconciliation file and a .ok suffix (for example, Acquirer_Activity_Detail_P003_88888888_20230108.csv.ok) to indicate that the file transfer is complete.
    Important : Before parsing a reconciliation file, the client should first determine whether the same-name .ok file exists to avoid reading a file whose transfer has not yet completed.

    How to perform reconciliation#

    Integrating parties need to record their own transaction data and match it against the reconciliation files provided by Evo Payment. Recommended process:
    1.
    Retrieve reconciliation files from the G2 platform or SFTP on a daily schedule;
    2.
    Check the same-name .ok marker file to confirm that the transfer is complete;
    3.
    Parse CSV files according to uniform rules (UTF-8 BOM, double quotation mark + comma delimiter, ***END*** ending);
    4.
    Use the transaction detail data files provided by Evo Payment as the basis for automated reconciliation;
    5.
    Difference records enter the exception handling process, and confirmation is completed through manual checks and operational reports.

    Learn more#

    Version and compatibility#

    The file version number is named according to P/T + 3 digits; new-version files are compatible with old-version fields;

    Large file splitting#

    Evo Payment supports configuring the maximum number of records in a single file
    Main purpose: The maximum record-count threshold for a single file can be configured. If the threshold is exceeded within the same daily cut-off cycle, files will be generated in batches.
    Scenario 1: Set a threshold of 10000; with 15000 transactions, two files will be generated
    Scenario 2: Set a threshold of 10000; with 30000 transactions, three files will be generated
    After the large file splitting function is enabled, a BatchNum (001–999) suffix is added to the filename. Report name example: Acquirer_Activity_Detail_(Version No)_(Inscode)_YYYYMMDD_(BatchNum)
    Next
    File-01 Activity_Detail Online Transaction Detail File
    Built with