Messaging API Integration Prerequisites

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

Custom sender name whitelisting

Message sender name restrictions vary by country. In majority of the countries it's possible to use an alphanumeric (letters, numbers and space) sender name up to 11 characters without the need of prior whitelisting. At the same time there are countries where custom sender name needs prior whitelisting by the mobile operator (notably Russia, Turkey and Ukraine) or is not available at all (notable US and Canada) due to SMS spoofing concerns. A default shortcode or longcode will be automatically applied as sender name if alphanumeric value is not available.

Please consult with your account manager for uptodate information on custom sender name whitelisting requirements.

Message content whitelisting

Several restrictions are in place regarding SMS messaging in India, particularly when it comes to the country’s National Do Not Call (NDNC) list (see more in the table below). These restrictions mainly apply to transactional messages that can be delivered to NDNC numbers, but require prior message text whitelisting. Marketing related messages will not be delivered to NDNC numbers.

Security

Messaging 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

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

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.

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