Security

HTTPS

Fortumo's Bundling Platform APIs use exclusively HTTPS (Hypertext Transfer Protocol Secure) protocol for a secure communication.

Body hash calculation for POST requests

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

Certificates

Fortumo supports TLS client authentication for callbacks. Every request that originates from Fortumo will use client certificate with the following CN:

  • api.fortumo.io

In order to verify the authenticity of the callbacks made by Fortumo you should be checking the following:

  1. Is the callback initiated using a certificate issued by one of the Fortumo approved Certificate Authorities
  2. Does the Common Name (CN) or DNS Subject alternative name (SAN) of the certificate match api.fortumo.io

JSON Web Tokens (JWT)

Redirect requests are signed using JSON Web Tokens (JWT). JWT is an open RFC 7519 standard for transmitting information between two parties. Using JWTs helps us to validate that all payment requests are initiated by the partner and none of the parameters have been tampered with by third parties.

Before using the JWT based authentication, you will need to share a public key with your Project Manager. Refer to Preparing SSH keys guide on how to generate the public and private key pair.

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) and expiration (exp) time of the token. Every timestamp needs to be in Unix epoch format, so an example payload could be:

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

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

SSH Keys

Every JSON Web Token is signed with an SSH key. In order to start testing, you will need to generate a key pair and make sure to share the public key with your Project Manager. For more information on SSH Key generation, please visit https://merchants.fortumo.com/integration-and-testing/hosted-dcb/generating-ssh-keys/

Whitelisting our server IP addresses

For additional layer of security you can also whitelist IP addresses Fortumo is using for initiating callbacks. To get the list of IP-s please contact your Project Manager.

If your security policy requires strict checking of the certificate issuer authority then please contact your project manager. Please also test your endpoints with unauthorised requests in order to make sure the verification layer is working as intended.

Endpoint security

The JWT in signed redirects can be decoded and read by users, so if you are passing the callbacks URLs to Fortumo in your requests, please make sure that your endpoints are secured.

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