Payments API integration prerequisites

Merchant account setup

In order to get started you would first need to create an account on Fortumo dashboard.

1. Create an account in Fortumo Dashboard and click "Create new service". From there you can activate Unified SDK service.
2. Once service is activated you are directed to API Keys section.
3. Generate a 4096 bit ssh key pair (publc and private keys will be generated) in OpenSSH format and paste the public key in the input box. You can follow instructions on how generate the keys here.
4. Now you have an access to Payments API.
5. Live routes will be enabled in the pre-live final testing when everything is ready on both sides.

Payment channel configuration

All Payments API operations are performed using available payment channels. Payment channel identifies a direct carrier billing route for a specific mobile operator, e.g. telenor-no and ais-th define Telenor Norway and AIS Thailand channels.

Every payment channel needs prior configuration for your merchant account, but please note if a certain channel is enabled for your account, then it does not guarantee that it's fully ready for production launch, as many telcos require additional configuration and product-based customization prior to launch.

In addition Fortumo will configure a sandbox channel which will act as a real DCB connection, but without any charges involved. You can learn more about channel configuration and their capabilities from Capabilities section. Please consult with your account manager for appropriate route configuration.

Security

Payments API can be used both with JSON Web Token based authorisation and certificate based authorisation, but we recommend you to use JSON Web Token based authorisation. You get read more about JWT tokens on JWT.io.

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

Validating callbacks made by Fortumo

Validating merchant hash in Fortumo callbacks

Make sure merchant hash in Fortumo callback payload matches your own.

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 integration manager.

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

Validating signature in callback header

Each notification sent to your server includes http header X-Fortumo-Content-Signature and it's value will be describing the request contents in the form of a JWT token. Parsing the JWT will result in the following parameters:

1
2
3
4
5
6
7

{
  "iss": "api.fortumo.com",
  "iat": 1536766126,
  "exp": 1539358126,
  "body_sha256": "0321385d3f67571815efebbb377a6fe9d2b4e205a87f3d5867de60b152560322",
  "key_signature": "26:bc:af:13:1a:f2:c6:bc:96:75:d6:ad:f0:50:e3:7c"
}

To validate the requests you will have to follow these steps:

1. Read key_signature parameter which indicates the key Fortumo is using for signing JWT
2. Validate signature of the JWT
3. If signature is correct then calculate sha256 hash of the notification request body and validate against body_sha256 parameter

Signature in callback header is an opt-in feature. In order to enable it for your callbacks and get the public key from Fortumo please contact your account manager.