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"
}
|
Getting the download link
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
|