Report API

• Introduction
  • Features
  • Login to the service
• Report API concept
  • List available report types - Definitions
  • Report generation
  • Report status
  • Download the report
• Report options
  • About data signal
    • What is the data signal
    • How do data-signal-triggered reports work
    • How often does the signal arrive
    • Which reports are generated by events
  • Data filtering
    • Available operators
    • Sorting criteria
  • Crontab expression
• Types of reports
  • Processing activity
  • Settlement
  • Disputes
  • Financial reconciliation

Introduction

The Report API allows you to export data to manage your business like the details of your transactions in order to perform your financial reconciliation, track your chargebacks, etc.

An API Reference is available to facilitate the report generation.

Features

Our Report API provides a full set of features including:

• Unique source (Datalake)
• Customizable report templates
• Scheduling options
• Filtering and sorting criteria
• Timezone definition
• Notification service: Email, Webhook
• Download options: HTTP, SFTP

Login to the service

The Report API is part of our new API accessible through this URL :

• Production: https://payment.dalenys.com/

First, you will need to authenticate through our Authentication API to get an access_token.

Report API concept

List available report types - Definitions

A definition is a type of report managed by Payplug. It identifies the resources that can be exported, declares the filters that can be used, etc,… Example of definitions:

• Settlement report
• Transactions
• Chargebacks

A definitioncontains the following information:

• An id, which must be used afterward to get the report
• The report name
• A quick description
• Default sort
• Available filters
• Available columns

The definition resource is read only.

See Definition Object for more details.

Report generation

The Report API can be used in 2 different ways:

• Execution: a one time “on-demand” export of your data whose primary purpose is to be used through our User Interface for testing or to obtain a specific one-time report for manual exploration purpose. See Execution Object for more details.

• Planner: a recurrent export of your data (like every morning) that you can configure in our system so we manage the generation of reports for you at a dedicated time. So you don’t have to store API secrets and scripting the call every morning on your side). The planner will automatically create a new execution using the template defined there. See Planner Object for more details.

Report status

On the Report API, you have the availability to follow the generation of your report with their status, according to the following available values:

• INITIALIZING
• PENDING: next to process
• EXPORTING: data extraction
• GENERATING: CSV file generation
• GENERATED: ready to download
• EXPIRED: file has been deleted and can’t be downloaded
• FAILED: something went wrong

When the status changes to GENERATED, your report is ready to be retrieved.

This parameter is available when you GET an execution or calling the /planner/{id}/status.

Download the report

When the report is GENERATED you can download it using a /download endpoint. Refer to the API documentation.

tips

Keep in mind that the report can be really huge and take a lot of time and bandwidth depending on your connection capacity.

Report options

You can change filter criteria, columns, time zone and sort options.

About data signal

What is the data signal

The data signal is a daily event that triggers the generation of reports, indicating that the data for the day is ready to be extracted for report creation.

How do data-signal-triggered reports work

The event-based system adds an extra layer of sophistication to recurring executions. Instead of running at fixed times, these planners are triggered by data readiness signals. This ensures that the reports are generated only when the data is fully prepared, providing the most accurate and up-to-date information. A merchant can create a planner for a weekly inventory report that should run every Friday. This report, however, will only be generated once the inventory data is fully updated and the data team sends the readiness signal. If the data is ready on Friday, the report runs as scheduled. If the data is delayed, the report waits, ensuring that the merchant always receives accurate and complete information.

How often does the signal arrive

Every day. But the report will be generated based the scheduled ferquency of the related planner. For example, consider a daily settlement report. With an event-based planner, the report will be generated every day, but only once the data team signals that the settlement data is ready. If the data is not ready, the report will wait. This is technically referred to as DAILY_DATA_PROCESSING. If a merchant sets up a settlement planner to run every Wednesday, it will only execute when the data signal is received on a Wednesday. If the signal comes on a different day, the report will not run, ensuring precision and relevance.

Which reports are generated by events

The data signal only works for reports related to a payout: Settlement and Financial Reconciliation.

Data filtering

Available operators

info

Operators are case insensitive

• like, startsWith, endsWith, contains
• lessThan, lessOrEqual, equal, greaterOrEqual, greaterThan
• in (followed by multiple value using “,” as separator)
• between (range defined by the after and before operators)

Sorting criteria

A sort criterion is composed of:

• A prefix symbolizing the sort order: + to sort ascending or - to sort descending
• The name of the column to sort (case insensitive).

info

This column must be marked as sortable in the report Definition.

A succession of multiple sorting criteria will be processed in order.

Example:

["-columnA", "+columnB"]

This will sort the rows by sorting columnA in ascending order first, and then by sorting columnB in ascending order.

Crontab expression

To schedule the generation of your report, you have to use the cron parameter in the planner object.

The cron parameter takes a crontab expression as value like:

• 0 0 0 ? * MON#1 (the first Monday in the month at midnight)
• 0 0 0 L-3 * * (third-to-last day of the month at midnight)

The string has six time and date fields separated by spaces:

  ┌───────────── second (0-59)
  │ ┌───────────── minute (0 - 59)
  │ │ ┌───────────── hour (0 - 23)
  │ │ │ ┌───────────── day of the month (1 - 31)
  │ │ │ │ ┌───────────── month (1 - 12) (or JAN-DEC)
  │ │ │ │ │ ┌───────────── day of the week (0 - 7)
  │ │ │ │ │ │          (0 or 7 is Sunday, or MON-SUN)
  │ │ │ │ │ │
  * * * * * *

Expressions example :

• “0 0 * * * *” = the top of every hour of every day.
• “*/10 * * * * *” = every ten seconds.
• “0 0 8-10 * * *” = 8, 9 and 10 o’clock of every day.
• “0 0 6,19 * * *” = 6:00 AM and 7:00 PM every day.
• “0 0/30 8-10 * * *” = 8:00, 8:30, 9:00, 9:30, 10:00 and 10:30 every day.
• “0 0 9-17 * * MON-FRI” = on the hour nine-to-five weekdays
• “0 0 0 25 12 ?” = every Christmas Day at midnight
• “0 0 0 L * *” = last day of the month at midnight
• “0 0 0 L-3 * *” = third-to-last day of the month at midnight
• “0 0 0 1W * *” = first weekday of the month at midnight
• “0 0 0 LW * *” = last weekday of the month at midnight
• “0 0 0 * * 5L” = last Friday of the month at midnight
• “0 0 0 * * THUL” = last Thursday of the month at midnight
• “0 0 0 ? * 5#2” = the second Friday in the month at midnight
• “0 0 0 ? * MON#1” = the first Monday in the month at midnight

The following macros are also supported:

• “@yearly” (or “@annually”) to run un once a year, i.e. “0 0 0 1 1 *”,
• “@monthly” to run once a month, i.e. “0 0 0 1 * *”,
• “@weekly” to run once a week, i.e. “0 0 0 * * 0”,
• “@daily” (or “@midnight”) to run once a day, i.e. “0 0 0 * * *”,
• “@hourly” to run once an hour, i.e. “0 0 * * * *”.

Types of reports

Processing activity

This report provides the details (e.g., card attributes, customer’s details, technical information, 3DS and fraud details, disputes and fraudulent transactions information) of processed operations: authorization, capture, payment, void, refund, credit.

Processing Activity Report Details

Settlement

This report contains all the operations (e.g., transactions, chargebacks, fees, guarantee, financial adjustments) which have been included in a specific wire transfer. This report allows you to reconcile your operations with your settlements.

Settlement Report Details

Disputes

This report provides details on disputed operations (e.g., RDR, chargebacks, representment, compliance, pre-arbitration, arbitration).

Disputes Report Details

Financial reconciliation

This report summarizes the operation types (e.g., sales, refunds, fees, guarantee, adjustments) included in a specific wire transfer.

Financial Reconciliation Report Details