Skip to main content

Reports

Many PSP group transactions into reports which are also accessible through the PayData API. Generally there are two types of reports:

  • Transaction reports
  • Settlement reports

Transaction reports​

Transaction reports are requested by the merchant for a specific time range or are automatically created by the PSP for set time intervals. PSPs that only provide transaction reports usually don't give PayData enough information to match a payout with the transactions it contains. A report can contain several payouts and the sum of the payout will not match the sum of the transactions.

Settlement reports​

Settlement reports are automatically generated by the PSP and group transactions and fees together with their associated payout.

The sum of all transactions and fees is equal to payout amount. PayData verifies this to ensure there are no missing transactions.

Example PSPs are: Kaufland, SumUp

Example PSPs are: Amazon, Adyen, EBay Payments, Klarna, Mirakl, Mollie, Stripe

The exact behavior varies between PSPs, and new cases can surface over time as PSP behavior changes. It's best to be prepared for the following cases:

  • Reports can span several months or even years with thousands of transactions.
  • Reports can have overlapping time ranges.
  • Reports might not have a payout if the balance is negative or held back.
  • Reports can have multiple payouts (manual or automatic).
  • Manually initiated payouts can break the scheduled payout interval of the PSP, making the report unavailable until an automatic payout occurs and the report is closed by the PSP.
  • The sum of all transactions PayData returns will not always be zero.
  • Old reports can suddenly appear and be processed by PayData.
  • There can be errors and warning processing a report. See below.

Report Processing​

Happy Path​

The following steps describe the normal processing of reports if no errors happen.

  1. PayData requests a list of payouts/reports from the PSP and lists them as Available.
  2. File based reports are Downloaded before they're processed.
  3. PayData begins Importing the reports from oldest to newest (if known).
  4. Successfully imported reports will then be returned as Imported.
  5. Reports are Skipped if they are empty or don't contain new transactions.
note

Some PSPs aggressively throttle API requests which can cause reports to be in the Available state for quite some time.

Unhappy Path​

Unfortunately errors can happen during the processing steps. PayData tries to recover from errors by retrying the processing step automatically but will give up after some time.

The exact number of retries or time that must pass until an error state is final, depends on the PSP and other factors like the returned error (see Final States) The Errors and Warnings of a report contain more information (see Errors & Warnings below).

DownloadError​

PayData failed to acquire the report contents. Downloading the report may be retried. Reasons include:

  • PSP is currently unavailable.
  • Insufficient permissions to access a specific report.
  • Report became unavailable for unknown reasons.

ImportError​

PayData failed to process or validate the report

  • PSP is currently unavailable.
  • PSP delivered an incomplete report.
  • Report is in a format PayData does not understand (File Based Accounts).
  • Report is missing transactions and an internal validation check fails.
  • Report payout amount is incorrect and an internal validation check fails.

Imported with Warnings​

Not all errors cause the import of the report to fail completely. Missing transactions or failure to validate the payout amount will ultimately result in a report that gets Imported with warnings.

Final states​

The state diagram contains the following possibly final states:

  • Imported
  • Skipped
  • DownloadError
  • ImportError

A state is final if the report does not contain Errors and Warnings where isTemporary is true. If an error or warning is marked as temporary, PayData will retry the processing of the report.

note

In support cases, the reprocessing of a report can be triggered at any time.

State casing

The names above (and in the diagrams) describe the state machine for readability. The state field returned by the API uses lowercase, underscore-separated values instead: available, downloaded, importing, imported, download_error, import_error, skipped. Match against these literal values in code — see the corrected example below.

Errors & Warnings​

Report-level errors and warnings follow the standard error/warning format. The two cases below are specific to report processing.

CaseStateExample

Payout validation failure

PayData will retry the import in case the report gets automatically corrected by the PSP.

ImportError
{
  // ...
  "state": "import_error",
  "warnings": [],
  "errors": [
    {
      "message": "Calculated payout amount (123.45 EUR) does not match payout of report (120.45 EUR).",
      "type": "ReportValidationFailure",
      "isUserActionRequired": false,
      "isTemporary": true
    }
  ]
}

Payout validation failure

PayData imported the report despite a validation error because no correction was made.

Imported
{
  // ...
  "state": "imported",
  "warnings": [
    {
      "message": "Calculated payout amount (123.45 EUR) does not match payout of report (120.45 EUR).",
      "type": "ReportValidationFailure",
      "isUserActionRequired": false,
      "isTemporary": false
    }
  ],
  "errors": []
}