Transaction Report Generation (S2S)

The Transaction Report Generation API allows clients to generate transaction reports in CSV or XLS format. Reports can be generated from presets (predefined report configurations by ID), via raw field selection (specifying exactly which fields to include), or through a server-to-server (S2S) streaming interface. All endpoints are under the base path /v1/report-generator. This guide covers all available endpoints, their parameters, and usage examples.

Base Path:/v1/report-generator

Content Types:

Requests: GET endpoints accept query parameters (URL-encoded) and the S2S endpoint (POST /s2s) expects a JSON body (Content-Type: application/json).
Responses: Successful report generation returns the report file bytes. The response includes appropriate Content-Type (text/csv for CSV, application/vnd.ms-excel for XLS) and a Content-Disposition header to prompt download as an attachment (e.g. Content-Disposition: attachment; filename="<report_name>.<ext>").

General Parameters & Conventions

Date/Time Format: All date-time filters use the format yyyy-MM-dd HH:mm:ss. For example: 2025-09-11 13:39:00. Ensure date strings match this exact pattern. If dateFrom or dateTo are omitted in GET requests, the API defaults to the last ~90 days (3 months) up to the current time.

Sorting Options: You can sort the report results by specifying sortBy and sortOrder parameters in GET requests.

sortBy: field name to sort by. Defaults to created_date if not provided. Accepted values (in snake_case) include: request_id, id, psp_tx_id, bin_card_country_code, device_ip_country_code, card_payment_brand, created_date, last_modified_date, merchant_id, merchant_mid, psp_id, psp_group_id, trx_currency, transaction_status, card_bin, card_last_four, user_phone, user_email, customer_id, user_first_name, user_last_name, referrer, is_3ds. (These correspond to fields of the transaction record.)
sortOrder: sort direction, either asc (ascending) or desc (descending). Default is desc.

📘
Note: For consistency, use the snake_case names for sortBy values as listed above. (The API may accept some camelCase equivalents internally, but it's best to stick to the documented snake_case names.)

Report Formats: The API supports CSV and XLS formats for output. This is specified with the format parameter (for GET endpoints) or in the JSON body (for S2S). The value is case-insensitive (you can use csv or CSV, etc.). Any other value will result in a 400 Bad Request (validation error). Ensure the format is exactly "csv" or "xls".

Endpoints

1. `GET /report-generator/{id}` - Generate Report from Preset

This endpoint generates a transaction report based on a preset report definition identified by its {id}. The preset must exist on the server; otherwise, a 404 error is returned. This is useful for generating reports from saved configurations without specifying all fields each time.

Query Parameters: (All parameters are passed as URL query strings.)

format (string, required): The output format of the report file. Must be either csv or xls (case-insensitive).
pspTxId (string, optional): Filter by PSP transaction ID.
requestId (string, optional): Filter by the request ID of the transaction.
cardPaymentBrand (string, optional): Filter by card brand (e.g., Visa, MasterCard).
dateFrom (string, optional): Start of date range filter (inclusive). Format: yyyy-MM-dd HH:mm:ss. If not provided, defaults to ~90 days before current time.
dateTo (string, optional): End of date range filter (inclusive). Format: yyyy-MM-dd HH:mm:ss. If not provided, defaults to current time.
merchantId (long, optional): Filter by a specific merchant’s ID.
merchantGroupId (long, optional): Filter by a specific merchant group ID.
merchantAccountId (long, optional): Filter by a specific merchant account ID.
merchantMid (string, optional): Filter by merchant MID.
pspId (long, optional): Filter by payment service provider ID.
currency (string, optional): Filter by transaction currency (ISO currency code).
transactionStatus (string, optional): Filter by transaction status (e.g., SUCCESS, FAILED, PENDING).
cardPan (string, optional): Filter by card PAN (card number) – typically by last four digits or full number as applicable.
userPhone (string, optional): Filter by user phone number.
userEmail (string, optional): Filter by user email address. (If provided, must be a valid email format.)
userFullName (string, optional): Filter by the user's full name.
referrer (string, optional): Filter by referrer (originating site or reference).
transactionType (string, optional): Filter by type of transaction (e.g., SALE, REFUND).
dataset (string, optional): Filter by dataset (context-specific usage).
customerId (long, optional): Filter by customer ID.
binCardCountryCode (string, optional): Filter by the country code of the card’s BIN (issuing country).
deviceIpCountryCode (string, optional): Filter by the country code of the device IP address.
is3DS (boolean, optional): Filter by whether 3-D Secure was used (true or false).
transactionId (long, optional): Filter by the transaction’s internal ID.
dateSource (string, optional): Specifies which date field the dateFrom/dateTo filter applies to. Typical values are
createdDate or lastModifiedDate (and possibly others depending on system capabilities). If omitted, it generally defaults to createdDate.

💡
Sorting: You may also include sortBy and sortOrder query parameters for sorting results (see Sorting Options above). If not specified, results are sorted by created_date in descending order by default.

Responses:

200 OK: Returns the report file. The response's body contains the file bytes (CSV or XLS content). The Content-Type will be text/csv for CSV reports or application/vnd.ms-excel for XLS. The Content-Disposition header is set to attachment; filename="<generated_name>.<ext>" (for example, report_123.csv), prompting a download.

404 Not Found: No report preset was found for the provided {id}. The response body may contain a message like "No Report Preset found for the specified id".

400 Bad Request: The request was invalid. This can happen if required parameters are missing or if a parameter fails validation (e.g., an invalid email format in userEmail, an unsupported format value, improperly formatted dates, etc.). The response body may include an error message indicating which parameter is invalid.

Example – Generating a Preset Report (CSV):

The following example uses curl to request a CSV report for preset ID 123, filtered to a specific date range and merchant, sorted by creation date descending. The output is saved to report_123.csv:

curl -G 'https://<host>/report-generator/123' \
  --data-urlencode 'format=csv' \
  --data-urlencode 'dateFrom=2025-06-13 00:00:00' \
  --data-urlencode 'dateTo=2025-09-11 23:59:59' \
  --data-urlencode 'merchantId=42' \
  --data-urlencode 'sortBy=created_date' \
  --data-urlencode 'sortOrder=desc' \
  -o report_123.csv

2. `GET /report-generator/raw` - Generate Ad-hoc Report (Selected Fields)

This endpoint generates a transaction report based on an ad-hoc selection of fields and filters, rather than a preconfigured preset. You must specify which fields (columns) you want in the report via the selectedFields parameters.

Query Parameters:

format (string, required): The output file format, csv or xls. (Case-insensitive.)
selectedFields (string, required, can be repeated): The list of fields/columns to include in the report. You must provide at least one selectedFields parameter. Each selectedFields value should be one of the allowed field names from the transaction data model (see list below). You can include multiple fields by repeating this parameter in the query string, e.g. selectedFields=id&selectedFields=requestId&selectedFields=trxAmount, etc.
reportName (string, optional): A custom name for the report file. If provided, this will be used in the output filename. Defaults to "Report" if not specified. (The API will append the appropriate .csv or .xls extension to this name in the Content-Disposition header.)
Filtering parameters: All the filtering query parameters supported by the preset endpoint (above) are also supported here.
This includes pspTxId, requestId, cardPaymentBrand, dateFrom, dateTo, merchantId, merchantGroupId, merchantAccountId, merchantMid, pspId, currency, transactionStatus, cardPan, userPhone, userEmail, userFullName, referrer, transactionType, dataset, customerId, binCardCountryCode, deviceIpCountryCode, is3DS, transactionId, dateSource. Their meanings and usage are the same as described in the previous section.
Sorting: You can also use sortBy and sortOrder here to sort the output (defaults are created_date and desc as explained earlier).

Allowed Values forselectedFields : The value for each selectedFields must be a property name of the TransactionFieldsReportDto (the data structure for report fields). Examples of valid field names include:

id, requestId, binCardCategory, cardPaymentBrand, binCardType, issuingBankName, 
binCardCountryCode, merchant, merchantAccount, callbackUrl, successRedirectUrl, 
failureRedirectUrl, cardBin, psp, cardLastFour, cardHolderName, requestThreeDSecure, 
orderCurrency, trxCurrency, referrer, language, orderAmount, trxAmount, transactionStatus, 
declineReason, declineCode, transactionType, userFirstName, userLastName, userAddress1, 
userCity, userCountry, userPostalCode, userEmail, userPhone, userDateOfBirth, orderDate, 
orderId, orderTitle, domainName, deviceIp, deviceIpCountryCode, createdDate, lastModifiedDate, 
captureAmount, is3DS

Any of the above fields can be requested. If an unknown or unsupported field name is provided, the API will likely respond with a validation error. You must include at least one field; multiple fields are allowed.

Validation Rules:

The format must be either csv or xls. If it’s missing or has any other value, the API returns a 400 Bad Request.
There must be at least one selectedFields specified. If none are provided, you’ll get a 400 error (validation error for empty selectedFields).
reportName cannot be an empty string if provided (a blank name will trigger a validation error).
If userEmail is provided as a filter, it must be a valid email address format.
dateFrom and dateTo must match the required date format (yyyy-MM-dd HH:mm:ss) if provided. If they are omitted, the API will default to the last ~3 months range (similar to the preset endpoint).

Responses:

200 OK: On success, the response body is the generated report file (CSV or XLS). The Content-Type and Content-Disposition headers are set as described earlier. If you provided a reportName, that name is used in the filename of the Content-Disposition (e.g., attachment; filename="Monthly Sales.xls" for the example below). If no reportName was given, a default name like "Report.csv" or "Report.xls" will be used.

400 Bad Request: The request was invalid. This can happen if any validation rule is violated — for example, missing format, no selectedFields, an invalid field name, blank reportName, improperly formatted dates, or an invalid email address in userEmail. The error message in the response will indicate the problem (e.g., "selectedFields must not be empty", "invalid email address", etc.).

Example - Generating a Raw Report (XLS) with Selected Fields:

The following example requests an XLS report including only the fields id, requestId, and trxAmount for transactions in August 2025. The report will be named "Monthly Sales.xls":

curl -G 'https://<host>/report-generator/raw' \
  --data-urlencode 'format=xls' \
  --data-urlencode 'selectedFields=id' \
  --data-urlencode 'selectedFields=requestId' \
  --data-urlencode 'selectedFields=trxAmount' \
  --data-urlencode 'reportName=Monthly Sales' \
  --data-urlencode 'dateFrom=2025-08-01 00:00:00' \
  --data-urlencode 'dateTo=2025-08-31 23:59:59' \
  -o "Monthly Sales.xls"

3. `POST /report-generator/s2s` - Generate Report via Server-to-Server (Streaming)

This endpoint is designed for server-to-server (S2S) integration, allowing you to stream a large report directly. The request is a JSON payload and requires authentication via special headers. The response streams the file content (particularly useful for large datasets).

Headers (Required):

x-merchant-key: Your merchant API key (as a string). This is used to authenticate the request.
x-merchant-secret: Your merchant API secret. Together with the key, this is used to authenticate and authorize the report generation request.

Both headers must be present and correct. If they are invalid or missing, the request will be rejected with a 401 Unauthorized.

Request Body (JSON): The body should be a JSON object with the following structure (Content-Type must be application/json):

{
  "dateFrom": "yyyy-MM-dd HH:mm:ss",        // required: start of date range
  "dateTo": "yyyy-MM-dd HH:mm:ss",          // required: end of date range
  "format": "csv or xls",                   // optional: output format (default is CSV if not provided)
  "dateSource": "createdDate or lastModifiedDate or other",  // required: which date field to filter by (default is createdDate)
  // ... (Note: Other filter criteria may not be supported in S2S call beyond the date range and source)
}

Fields in the JSON body:

dateFrom (string, required): Start of the date range to include in the report (format yyyy-MM-dd HH:mm:ss). This must be provided and not blank.
dateTo (string, required): End of the date range for the report (format yyyy-MM-dd HH:mm:ss). Must be provided and not blank.
format (string, optional): Report format, either "csv" or "xls". Defaults to "csv" if omitted.
dateSource (string, required): Which date field to use when filtering by the above date range. Typically "createdDate" or "lastModifiedDate" (or other date fields available in the system). Defaults to "createdDate" if not specified. This field should be a non-empty string corresponding to a valid date type; if an invalid value is given, a 400 error will result.

📘
Note: All required fields must be non-blank strings in the JSON (per @NotBlank validation in the API). The x-merchant-key and x-merchant-secret are used to identify and authenticate the merchant; the server will validate these credentials before processing the report.

Responses:

200 OK: If the credentials are valid and the request passes validation, the response will stream the report content. The response headers will include the appropriate Content-Type (text/csv or application/vnd.ms-excel) and a Content-Disposition (e.g., attachment; filename="s2s_report.csv" if no specific name is set).
The body is sent as a stream (for example, as a Flux of data buffers on a reactive stack), which effectively downloads the report content in a streaming fashion. The set of columns included in this S2S report is all available transaction fields (the full TransactionFieldsReportDto fields in a predefined order), since this endpoint is intended to dump the complete transaction data within the specified date range.
401 Unauthorized: Authentication failed. This means the x-merchant-key and/or x-merchant-secret were missing or invalid. The response body may contain a message like "Invalid merchant credentials". Ensure the credentials are correct and associated with your account.
400 Bad Request: The request did not pass validation. This could be due to missing or improperly formatted dateFrom/dateTo/dateSource, or an invalid format value. The error message will indicate the issue (for example, a blank required field or a date format mismatch).

Example - S2S Streaming Report (CSV):

In this example, a POST request is made to generate a CSV report for all transactions in August 2025. The x-merchant-key and x-merchant-secret headers are included for authentication. The output will be saved to s2s_report.csv:

curl -X POST 'https://<host>/report-generator/s2s' \
  -H 'Content-Type: application/json' \
  -H 'x-merchant-key: <your_key>' \
  -H 'x-merchant-secret: <your_secret>' \
  -d '{
        "dateFrom": "2025-08-01 00:00:00",
        "dateTo": "2025-08-31 23:59:59",
        "format": "csv",
        "dateSource": "createdDate"
      }' \
  -o s2s_report.csv

Additional Notes

Default Date Range: If dateFrom/dateTo are omitted in the GET endpoints, the system will automatically use a default range covering approximately the last 3 months up to now. It’s generally recommended to specify a date range to control the size of the report.
Case Sensitivity: The values for format are case-insensitive, but other string filters (like cardPaymentBrand, currency, etc.) might be case-sensitive depending on implementation. Typically, use the exact values as they are stored (e.g., use uppercase currency codes like "USD").
Field Naming: Use the snake_case field names for sorting and filtering parameters as documented. In some contexts, the API may accept camelCase, but the snake_case is the standard in query parameters (e.g., use created_date not createdDate in sortBy).
Error Responses: The structure of error responses (400 Bad Request, etc.) may vary depending on the global error handler in the API. Typically, validation errors will produce a message indicating which parameter is invalid or missing. For example, if you pass an incorrectly formatted date, the error might mention the expected format. If multiple errors occur, you may receive a list of error messages.
Presets vs Raw Reports: A "preset" report (GET /report-generator/{id}) corresponds to a saved configuration (including a predefined set of fields and filters) on the server. In contrast, the "raw" report endpoint allows the client to specify exactly which fields to include for each request. Use presets for convenience and consistency, and raw reports for flexibility when you need custom output columns.
Security (S2S): Keep your x-merchant-key and x-merchant-secret confidential. These are like credentials – anyone with these could potentially generate reports from your data. Always use HTTPS to protect these secrets in transit. The S2S endpoint is intended for backend-to-backend communication, not for use directly from a browser or client-side, since it returns potentially large data streams and requires secret keys.

This guide provides a comprehensive overview of the Transaction Report Generation API. By following the above endpoint specifications and examples, you can programmatically generate transaction reports in the desired format and integrate this functionality into your systems.

Transaction Report Generation (S2S)

General Parameters & Conventions

Note: For consistency, use the snake_case names for `sortBy` values as listed above. (The API may accept some camelCase equivalents internally, but it's best to stick to the documented snake_case names.)

Endpoints

1. `GET /report-generator/{id}` - Generate Report from Preset

Sorting: You may also include `sortBy` and `sortOrder` query parameters for sorting results (see Sorting Options above). If not specified, results are sorted by `created_date` in descending order by default.

2. `GET /report-generator/raw` - Generate Ad-hoc Report (Selected Fields)

3. `POST /report-generator/s2s` - Generate Report via Server-to-Server (Streaming)

Note: All required fields must be non-blank strings in the JSON (per `@NotBlank` validation in the API). The `x-merchant-key` and `x-merchant-secret` are used to identify and authenticate the merchant; the server will validate these credentials before processing the report.

Additional Notes

General Parameters & Conventions

Note: For consistency, use the snake_case names for sortBy values as listed above. (The API may accept some camelCase equivalents internally, but it's best to stick to the documented snake_case names.)

Endpoints

1. GET /report-generator/{id} - Generate Report from Preset

Sorting: You may also include sortBy and sortOrder query parameters for sorting results (see Sorting Options above). If not specified, results are sorted by created_date in descending order by default.

2. GET /report-generator/raw - Generate Ad-hoc Report (Selected Fields)

3. POST /report-generator/s2s - Generate Report via Server-to-Server (Streaming)

Note: All required fields must be non-blank strings in the JSON (per @NotBlank validation in the API). The x-merchant-key and x-merchant-secret are used to identify and authenticate the merchant; the server will validate these credentials before processing the report.

Additional Notes

Note: For consistency, use the snake_case names for `sortBy` values as listed above. (The API may accept some camelCase equivalents internally, but it's best to stick to the documented snake_case names.)

1. `GET /report-generator/{id}` - Generate Report from Preset

Sorting: You may also include `sortBy` and `sortOrder` query parameters for sorting results (see Sorting Options above). If not specified, results are sorted by `created_date` in descending order by default.

2. `GET /report-generator/raw` - Generate Ad-hoc Report (Selected Fields)

3. `POST /report-generator/s2s` - Generate Report via Server-to-Server (Streaming)

Note: All required fields must be non-blank strings in the JSON (per `@NotBlank` validation in the API). The `x-merchant-key` and `x-merchant-secret` are used to identify and authenticate the merchant; the server will validate these credentials before processing the report.