Automatic export via the Console API

The Console API is available on your test (Stage) and production environments. Use it to automatically export the data displayed in the Transactions and Financial reports modules of HiPay Console. In this article, you will find all the necessary information for one-time and recurring exports made via our Console API.

To view the technical documentation of the Console API endpoints, please visit the following URLs:

• Stage:  https://stage-console.hipay. com/api/docs
• Production:  https://console.hipay.com/api/docs

You will be able to test every endpoint described in this document.

Generating a temporary key

The first step is to generate a token (temporary key) for identification purposes. To do this, make an API POST call to the URL:

• https://console.hipay.com/api/login 

In the body, enter the following:

{
    "username": "username@hipay.com",
    "password": "ChangeMe"
}

Here is an example of an answer:

{
    "token_type": "Bearer",
    "expires_in": "3600",

    "access_token": "TOKEN_HERE",
}

You can then call the following endpoints and specify the token you obtained in the response above in the headers of your requests.

Creating an export

There are several types of exports. To start, make an API POST call to the URL: https://console.hipay.com/api/exports.

In the header, enter the token you obtained earlier:

{
    "x-Authorization": "Bearer [YOUR TOKEN]",
    "Content-Type": "application/json"
}

Simple export

In a simple export, the file is generated directly after its creation. Here is an example of a body:

{
"filePrefix": "MY_PREFIX",
"module": "transaction",
"columns": "{\"merchant_order_id\":{\"label\":\"Order ID\"},\"trxid\":{\"label\":\"Transaction ID\"}, \"captured_amount\":{\"label\":\"Captured amount\"}}",
"filters": "{\"captured_date_interval\":\"pd\", \"payment_means\": \"mastercard\"}",
"separator": "semicolon",
"recurrence": "once",
"receiveByEmail": false,
"config": "{“granularity”: “operation”}"
}

Here, the "config" parameter is set to create an export per payment operation with the following JSON: “{“granularity”: “operation”}”.

You can also create an export per transaction by setting the granularity to "transaction": “{“granularity”: “transaction”}”.

Recurring export

Your export can be recurring. Depending on your settings, the file can be automatically created. For a recurring export, use the same URL for an API POST at https://console.hipay.com/api/exports.

Here is an example of a body creating a daily export that lasts 30 days:

{
"filePrefix": "MY_PREFIX",
"module": "transaction",
"columns": "{\"merchant_order_id\":{\"label\":\"Order ID\"},\"trxid\":{\"label\":\"Transaction ID\"}, \"captured_amount\":{\"label\":\"Captured amount\"}}",
"filters": "{\"captured_date_interval\":\"pd\", \"payment_means\": \"mastercard\"}",
"separator": "semicolon",
"recurrence": "daily",
"nbOccurrence": "30",
"receiveByEmail": true,
"config": "{“granularity”: “transaction”}"
}

Setting up a recurring export

A recurring export must contain a predefined date filter. You can use the predefined date intervals:

• pd: Past day
• cw: Current week
• pw: Past week
• cm: Current month
• pm: Past month
• cq: Current quarter
• pq: Past quarter
• cy: Current year
• yy: Last twelve months
• custom: Custom

An “interval” based on the “created date” will look like this:

{
…
 "filters": "{\"created_date_interval\":\"pd\"}",
…
}

To create a recurring export with a custom interval, use the “authorized_by_payment_means_date” column as for the other predefined filter and define an “_interval”, a “_date_from” and a "_date_to”:

{
  "authorized_by_payment_means_date_interval": "custom",
  "authorized_by_payment_means_date_from": "2019-01-01",
  "authorized_by_payment_means_date_to": "2019-06-15"
}

Recurring exports can be configured in various ways.

It is possible to set an infinite number of occurrences by not specifying a “nbOccurrence” or “endRecurrenceDay”.

You can also choose whether a monthly export (with defined occurrences or not) is generated on the first or last day of the month by using the values “first_day” or “last_day” to set the “recurrenceDay” parameter. For weekly exports, you can set it with values going from 1 to 7, depending on the day of the week during which you want to receive the export.

Finally, to set a maximum number of occurrences, configure “nbOccurrence” with the desired number of occurrences, or “endRecurrenceDay” with the date after which the exports will no longer be generated, in YYYY-MM-DD format.

For example:

• For a monthly recurrence that lasts six months, set the “recurrence” parameter to “monthly” and the “nbOccurrence” parameter to 6.
• For a weekly recurrence that ends on a defined date, set the “recurrence” parameter to “weekly” and the “endRecurrenceDay” parameter to June 15, 2023, i.e., “2023-06-15”. Set the “recurrenceDay” parameter to 3 to receive the export every Wednesday.

The different parameters and possible values

Response example

{
  "exportId": 1234,
  "dateCreated": "2020-01-01T11:00:00+01:00",
  "dateUpdated": null,
  "exportFiles": [
      {
          "fileId": 5801,
          "dateCreated": "2020-01-01T11:00:00+01:00",
          "filename": "MY_PREFIX_20230125-110006_91",
          "hash": "5813580648388153ec741b3816704b858b71253d494cd6a47c6d2782d5b75293a942a7d35b343b88c8b2c8fa19c8b3ad1ddf0a65f4f9a8658afe746e31960b1a",
          "status": "created",
          "nbItems": null
      }
  ],
  "filePrefix": "ALL_ACCOUNTS_CAPT",
  "emails": null,
  "module": "transaction",
  "status": "active",
  "columns": "{\"merchant_order_id\":{\"label\":\"Order ID\"},\"trxid\":{\"label\":\"Transaction ID\"}, \"captured_amount\":{\"label\":\"Captured amount\"}}",
  "filters": "{\"captured_date_interval\":\"pd\", \"payment_means\": \"mastercard\"}",
  "urlFilters": null,
  "separator": "semicolon",
  "recurrence": "once",
  "recurrenceDay": null,
  "nbOccurrence": 5,
  "endRecurrenceDay": null,
  "receiveByEmail": false,
  "user": "/api/users/123",
  "userId": 123,
  "config": "{“granularity”: “operation”}",
  "error": null
}

Possible errors

When creating an export, several errors can occur, such as:

• > “The recurrence “daily” must be used with a predefined date interval”
  A recurrent export (recurrence != once) must have a predefined date filter.
• “The recurrence “daily” must be used with a “receiveByEmail” field to true.”
  A recurrent export (recurrence != once) must have “receiveByEmail” field set to “true”.
• > “At least one similar export is already in progress”
  The same export has already been launched, but has not been completed.
• > “xxxxx is not a valid slug”
  The slug of the column name (ID) does not correspond to an existing column.
• > “xxxxx contains illegal characters”
  The label of a column must not contain special characters.
• > “xxxxx is not a valid JSON”
  The value sent is not a JSON (fields: filters, columns).
• > “filePrefix incorrect”
  The “file prefix” must contain 30 characters maximum and respect the following regex: /^([\w]|[à-ú]|[À-Ú]|[-_\[\]\.]){1,30}$/
  
  

Retrieving the export file

In case of a recurring export, call the GET endpoint /api/exports/[export ID]/files (with the export ID obtained in the response during creation) to get the list of generated files for the specified export. Retrieve the ID of the exportFile you are interested in, then call the GET endpoint /api/export-files/[file ID]?hash=[file hash] with the following headers:

{
    "x-Authorization": "Bearer [YOUR TOKEN]",
    "Content-Type": "application/zip"
}

Example of a call with CURL that lets you recover the file’s content:

curl -X GET "https://console.hipay.com/api/export-files/1234?hash=123" -H "accept: application/zip" -H "X-Authorization: Bearer [MON TOKEN]" --output [DOSSIER DE DESTINATION]

If you want to receive the file by e-mail, use the following URL, still in GET: /api/export-files/[file ID]/email?hash=[file hash].

Please note that the files are only available to download:

• during one day for simple exports and daily recurring exports,
• during seven days for non-daily recurring exports.

Generating an export again

Once a day, you can generate an export again under the same conditions as the first time.

To do so, call the GET endpoint /api/export-files/[export ID]/regenerate?hash=[file hash] with the following headers:

{
    "x-Authorization": "Bearer [YOUR TOKEN]",
    "Content-Type": "application/zip"
}

Example of a CURL call:

curl -X GET "https://console.hipay.com/api/export-files/1234/regenerate?hash=123" -H "accept: application/zip" -H "X-Authorization: Bearer [MON TOKEN]" --output [DOSSIER DE DESTINATION]

Fill in the “send_by_email” parameter to receive the export by email.

Related articles: 

• Simple export
• Recurring exports list