Reporting API via SSL

Generating and downloading reports with SSL authentication method is reccommended for PSMS API and Web SDK Merchants. This keeps API authentication methods consistent overall the integration.

Initiating report generation

Make GET request to report generation endpoint corresponding to the required report type:

Report Report type Endpoint URL
Revenue revenue https://api-reports.fortumo.io/api/reports/revenue/new
Detailed Revenue revenue_detailed https://api-reports.fortumo.io/api/reports/revenue_detailed/new
Detailed Revenue Finalized revenue_detailed_finalized https://api-reports.fortumo.io/api/reports/revenue_detailed_finalized/new

What is the difference between detailed revenue and detailed revenue finalized reports?

  • If you would like to view transactions in the report based on payment started timestamp then choose a detailed revenue report.
  • If you would like to view transactions based on payment completion timestamp then choose a detailed revenue finalized report.
Request GET parameters
Name Description
from Start date value, format YYYY-mm-dd
to End date value, format YYYY-mm-dd
key Reporting API key
sig Signature, MD5 hash. Signed with Reporting API secret. Signature is added as sig parameter and calculated as MD5 checksum of the request parameters and secret concatenated together. Before calculating the signature, it is important to sort the parameters alphabetically.

Note that the Detailed revenue finalized report is designed for daily workflows and cannot be requested for longer than one day period.

Example sig calculation
  1. Set parameters in alphabetical order: from=2018-08-01key=a689dbafe56d88d7b81b63afd7d53142to=2018-08-31
  2. Add secret value to the string: from=2018-08-01key=a689dbafe56d88d7b81b63afd7d53142to=2018-08-31a892bf7162836d4ab15bad10fc3bbf2857469e43
  3. Calculate md5 has from the string: bc4bd607b61cf39295541306f0ed5b50
  4. Use md5 hash as the sig parameters: https://api-reports.fortumo.io/api/reports/revenue/new?from=2018-08-01&to=2018-08-31&key=a689dbafe56d88d7b81b63afd7d53142&sig=bc4bd607b61cf39295541306f0ed5b50
Response parameters
Name Description
state Shows if the file is available for downloading. [new | completed | failed]
id Unique name to identify the specific report file.
Example response
1
2
3
4
{
    "state": "new",
    "id": "6ea6639395bb3be2d512504c92930c17"
}
Error codes
Code Description
400 Malformed request, required parameters missing.
403 Permission denied, authentication failed.
500 Internal error has occurred.

Checking report generation status

Status checks must not be more frequent than once every 60 seconds.

Make GET request to report status check endpoint:

https://api-reports.fortumo.io/api/reports/status

Request parameters
Name Description
id Unique ID value for the CSV file, returned for the first API request.
key Reporting API key
sig Signature, MD5 hash.
Example request

https://api-reports.fortumo.io/api/reports/status?id=6ea6639395bb3be2d512504c92930c17&key=0123456789abcdef0123456789abcdef&sig=86719074b00648a0b9d008da8d01370d

Response parameters (JSON)
Name Description
state Shows if the file is available for downloading. [new | completed | failed]
id Unique name to identify the specific report file.
Example responses (JSON)

In progress:

1
2
3
4
{
    "state": "new",
    "id": "6ea6639395bb3be2d512504c92930c17"
}

Completed:

1
2
3
4
{
    "state": "completed",
    "id": "6ea6639395bb3be2d512504c92930c17"
}

Failed:

1
2
3
{
    "error": "Report not found"
}

Report download

After report generation status check has returned completed, generated CSV file can be downloaded by making GET request to:

https://api-reports.fortumo.io/api/reports/report

Request parameters
Name Description
id Unique ID value for the current CSV file, returned when initiating report generation
key Reporting API key.
sig Request signature, MD5 hash.
Example request
1
2
GET https://api-reports.fortumo.io/api/reports/report?id=6ea6639395bb3be2d512504c92930c17&key=0123456789abcdef0123456789abcdef&sig=f2947677459d06309151f79e2504c5e2 HTTP/1.1
Accept-Encoding: gzip, identity
Response
1
2
Status: 302 Found
Location: https://payments-api-reports-storage-production.s3.eu-west-1.amazonaws.com/1d2565965bb505e72133e6a914560da0/revenue_detailed/6ea6639395bb3be2d512504c92930c17.csv?X-Amz-Security-Token=f9aa06fc70692acfc49aae67fdb3fc412148c801344ce619aca545e19d087d86...%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200304T152253Z&X-Amz-SignedHeaders=host&X-Amz-Expires=172800&X-Amz-Credential=114d953095388541ccf021a7b2f51cae%2F20200304%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Signature=edeaaff3f1774ad2888673770c6d64097e391bc362d7d6fb34982ddf0efd18cb

Follow the Location to begin the download. Report will be downloaded as a semicolon separated UTF-8 CSV format file.

Note Setting the Accept-Encoding header as gzip will use compression for the transport. When no Accept-Encoding header is set we treat it as if it was set as identity

Note that the location returned in the 302 Found redirect will expire for security reasons

Help us improve our Merchants Portal. Was this article helpful?