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
  • Data filtering
    • Available operators
    • Sorting criteria
  • Crontab expression
• Types of reports
  • Processing Activity
  • Settlement
  • Disputes

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.

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’s attributs, 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 (RDR, chargebacks, representment, compliance, pre-arbitration, arbitration).

Disputes Report Details