Reporting API via JWT

Generating and downloading reports with JWT authentication method is reccommended for Unified SDK and Payments API Merchants. This keeps API authentication methods consistent overall the integration.

Report types

Report Report type
Revenue revenue
Detailed Revenue revenue_detailed
Detailed Revenue Finalized revenue_detailed_finalized
Request parameters
Parameter Type Required Description
from_date String Mandatory Start date of the report , e.g. 20200101
to_date String Mandatory End date of the report, e.g. 20200222
merchant String Mandatory Your merchant id. e.g: 93d9523134eee0f22716e49093af881a
operation_reference String Mandatory The operation_reference of the request, e.g. report_4
callback String Mandatory Callback URL to be used for receiving payment callbacks. Example: https://www.example.com/payment
Callback parameters
Parameter Type Required Description
report_token String Mandatory The id of your generated report. e.g. d16ca98fe015a1fd249baf157efbb553
report_state String Mandatory The state of current report. e.g. ready
merchant String Mandatory Your merchant id. e.g: 93d9523134eee0f22716e49093af881a
operation_reference String Mandatory The operation_reference of the request, e.g. report_4
error Object Optional In case errors happen an errorcode and description is listed. Example: 602
timestamp Datetime Mandatory Timestamp of the sent callback. Example: 2016-08-22T09:25:54.394Z

Generating the report

First step is to generate a report by defining the time period and the type of report you wish to download.

1
2
3
4
5
6
7
8
9
10
11
12
POST /reports/revenue_detailed/ HTTP/1.1
Host: api-jwt.fortumo.io
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9....CgVKRghGWI6-QjMv8JpJi1GarWaQ06CG9d0c1PDFek

  {
    "from_date": "20200101",
    "to_date": "20200222",
    "merchant": "18f0d56af36d3a3837305ffb290f05c7",
    "callback": "https://example.com/payments",
    "operation_reference": "report_4"
  }

After the POST request a callback is sent to the your endpoint with relevant report ID.

1
2
3
4
5
6
7
8
{
  "report_token": "d16ca98fe015a1fd249baf157efbb553",
  "report_state": "ready",
  "merchant": "18f0d56af36d3a3837305ffb290f05c7",
  "operation_reference": "report_4",
  "error": {},
  "timestamp": "2020-05-07 10:25:42.122"
}

A simple GET request with relevant report_token will provide you a URL to download the report.

1
https://api-jwt.fortumo.io/reports/{report_type}/{merchant}/{report_token}

1
2
3
4
GET /reports/revenue_detailed/18f0d56af36d3a3837305ffb290f05c7/d16ca98fe015a1fd249baf157efbb553 HTTP/1.1
Host: api-jwt.fortumo.io
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9....CgVKRghGWI6-QjMv8JpJi1GarWaQ06CG9d0c1PDFek

The URL will be provided in the Location header inside response headers.

1
2
3
4
5
6
7
Server: nginx
Date: Mon, 11 May 2020 12:43:15 GMT
Content-Type: application/json;charset=utf-8
Content-Length: 0
Connection: keep-alive
Accept-Encoding: application/json
Location: https://payments-api-reports-storage-production.s3.eu-west-1.amazonaws.com/18f0d56af36d3a3837305ffb290f05c7/revenue_detailed/d1320dfgr5675464

JSON Web Token based authentication

We strongly advise you to use one of available JWT token libraries as this significantly simplifies token generation and helps in avoiding common mistakes. Refer to JWT.io for a full list of available libraries for each programming language

JWTs are composed of three parts - header, payload and signature. JWT header identifies the algorithm that is used for generating the token signature. Fortumo currently supports tokens signed with RS256 algorithm, so the header of the decoded JWT should always be following:

1
2
3
4
{
  "alg": "RS256",
  "typ": "JWT"
}

In the payload section we expect you to specify the issuing (iat), not before (nbf), expiration (exp) time of the token and (body_sha256) in case of POST/PUT request, value of which is a sha256 checksum of the exact request body. Every timestamp needs to be in Unix epoch format, so an example payload could be:

1
2
3
4
5
6
{
  "exp": "1506770190",
  "nbf": "1506597390",
  "iat": "1506683790",
  "body_sha256": "f682272834c84d3c3aa8dfaef3d11b7c07b0c644dfe4eeb41f7c7c0fef865878"
}

The body_sha256 claim in the JWT header must be equal to the sha256 checksum of the request body.

JWTs are signed with the private key of your RSA key pair, so the final part of the decoded JWT will be in following format:

1
2
3
4
5
6
RSASHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  [public_key],
  [private_key]
)

After you have completed generating a unique token for your request, simply add the token value in your request Authorization header.

1
Authorization: Bearer {JWT}

Full headers example:

1
2
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJleHAiOjE ... CJhbGciOEgVU0U4vvGg_a2rCP6XHQ
Help us improve our Merchants Portal. Was this article helpful?