Skip to content

Get Settlement File for Company

Endpoint

GET/api/v1/merchant/files/{fileType}/

Retrieve your settlement and custom fee reports as CSV files for transactions within the month.

This endpoint allows card program owners to retrieve financial reports in CSV format, providing a structured view of fees, revenue, and transaction data for reconciliation. When a report is requested, a webhook event (eventType = files) will be triggered.

Path Parameters

Name Type Required Description
fileType string ✅ The type of report to retrieve (see available file types below).

Available File Types

File Type Description Use Case
monthly A complete list of all transaction events that impacted your master account balance for a given month. Helps reconcile cardholder transactions and understand their impact on your master account balance over a monthly period.
daily A complete list of all transaction events that impacted your master account balance for a specific day. Helps reconcile cardholder transactions and understand their impact on your master account balance over a daily period.
fee Provides details on FX and ATM fees charged to cardholders, representing revenue earned by your card program. Helps track revenue from FX and ATM mark-up fees, which are deducted from your monthly invoice as revenue generated.
monthlyTransactionFees A breakdown of transaction-related fees or revenue per transaction. Helps verify transaction-level fees or revenue for accurate reconciliation at the individual transaction level in a given month.
monthlyNonTransactionFees A breakdown of non-transactional costs such as card issuance fees and maintenance charges. Helps reconcile operational costs associated with running your card program, excluding transaction-based fees.
dailyTransactionFee A breakdown of transaction-related cost or revenue per transaction. Helps verify transaction-level costs or revenue for accurate reconciliation at the individual transaction level in a given day.

Download Window ⚠️

The download URL available from the files webhook expires after 5 minutes. Make sure to download your report within this timeframe.

How to Retrieve These Reports

  1. Select your desired report type:
  2. For Reconciliation: Use the daily or monthly reports to track all transactions affecting your master account balance.

  3. For Monthly Invoice Breakdown: Use dailyTransactionFee, monthlyTransactionFees, monthlyNonTransactionFees, and fee reports.

  4. Specify the date query parameter:

  5. Daily Reports: Request on or after T+1 (2 days after the queried date). Specify the exact date (YYYY-MM-DD).

  6. Monthly Reports: Request on or after the 2nd day of the following month. Specify any date within the month (YYYY-MM-DD).

  7. Submit the request to the endpoint.

  8. The report will include all data up to 11:59 PM UTC on the selected date.

Example Request

GET /api/v1/merchant/files/monthly/

Response

{
  "message": "File is being generated, link will be provided via webhook",
  "reference_id": "1741596933518"
}

Response Codes

Status Code Description
200 OK File request successfully initiated. A webhook will provide the download link.
400 Bad Request The provided date must be at least two days in the past.
401 Unauthorized Authentication failed.
500 Internal Server Error Server error.