Payments API Integration Prerequisites

Payments API is an on demand product. In order to gain access to the product and enable payment routes, please contact your account manager, who will configure it for your Fortumo account.

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

Before using the JWT based authentication, you will need to share a public key with your Account 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

TLS client authentication (deprecated)

In case you decide to integrate Fortumo payments using TLS client based authentication, you will need to share with our team the Common Name (CN) of the certificate that you will be using. For account configuration, please get in touch with your account manager. Please note that Fortumo only accepts certificates that have been issued by Fortumo approved Certificate Authorities. List of Fortumo approved Certificate Authorities is available here.

When using TLS client based authentication, please also note that we are checking the full certificate chain. Therefore it is important that the certificate chain that you are attaching to the request also includes intermediate certificates. Additional username/password validations are not supported.

Validating callbacks made by Fortumo

Validating client certificate

Fortumo supports TLS client authentication for merchant 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
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.

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