Fortumo Mobile Payments / Premium SMS API technical specification

Mobile Payments / Premium SMS API is the most flexible service type in Fortumo. It allows you to create practically any SMS service, that you could think of, but it requires some programming skills and a web-server where you could host your program (for example as a PHP-script). Interaction between our server and your script will be conducted with HTTP GET requests. There are three possible types of HTTP requests, which are described below. The parameters present in these requests are always the same. The most important and obligatory in message processing is the first type.

Message delivery

When your service receives a message, Fortumo will make an HTTP GET request to the URL that you have specified in the service configuration (for example http://yourdomain.com/sms.php). The content that Fortumo receives from your URL (or actually the first 120 characters of it) is then sent back to the user as a reply message. The parameters of that HTTP GET request specify the sender's phone number, message content etc. So you can use all that information to generate the reply message.

Billing reports

In countries with MT billing operators report if billing was successful or failed upon reply message delivery attempt. If you wish to receive this information, you should enable billing reports in your Premium service configuration. We will send you a billing report on the indicated URL after the message delivery. Any answer from your script will be counted as successful delivery. Your answer to billing report is not going to be forwarded to operator, so you can't use billing reports request to deliver reply message. Use first request.

Testing your script

Your account has a built-in testing functionality. After configuring your script's URL in your account, you can go to "Test" tab and initiate a test request from our server to your script. The parameter test will be present in test request and set to true.

message

Message content minus keywords. Thus if the message was TXT KEY 123, then this parameter is 123. The parameter is empty if there was only the keyword and no additional text in the message.

sender

Message sender's phone number in international format without the plus sign. For example, 4560123456 or 358401234567. In some countries, due to end-user privacy protection rules, this parameter may be blank or encrypted by mobile operator.

country

The country code of the sender's mobile operator. Two character codes are used according to ISO 3166-1 standard (SE for Sweden, FI - Finland, NO - Norway, LT - Lithuania, LV - Latvia, EE - Estonia etc). Please also note that this is NOT necessarily the actual location of the sender. For example the sender with a Swedish phone, could be sending a message while being roaming in Norway, and you would still have SE in the country field.

price

The end user price of the message in the local currency, including VAT.

currency

The local currency symbol according to ISO 4217 (EUR, SEK, NOK, DKK, LTL, LVL, EEK, USD, GBP etc).

service_id

A string that identifies this Fortumo service. For example f7fa12b381d290e268f99e382578d64a. If you have many services with the same URL, then you can use this field to determine which service the message is for.

message_id

A string that is unique for each message that your service receives.

keyword

The keyword part of the message. Thus if the message was TXT KEY 123, then this parameter is TXT KEY.

shortcode

The short code that the message was sent to.

operator

Name of the sender's mobile network operator.

billing_type

Can be MO or MT. Read more about billing types in Fortumo FAQ.

status

Billing status, which is either pending(in message delivery request), ok or failed(in billing report).

test

This parameter is present only when message is sent through Fortumo testing interface by yourself and it's value is always 'true'.

sig

Request signature that you may check, to make sure the request is originating from Fortumo. See below under Security to find out how.

It is important to make sure that the service script is called by Fortumo and not someone else. There are several security measures, that satisfy most of the service providers:

1. 
   Check whether the IP address of the server making the request belongs to one of Fortumo's servers. Our current IP addresses are 81.20.151.38, 81.20.148.122, 79.125.125.1 and 209.20.83.207. We will let you know by e-mail when they change. In PHP you can check this with $_SERVER["REMOTE_ADDR"] variable.
2. 
   Choose not so obvious name for your directory or script. For example http://yourdomain.com/sms.php is not as good as http://yourdomain.com/go850g3oigjrtog/sms.php.
3. 
   Check that the attached signature matches. All the requests are signed with the shared secret only known to you and Fortumo. You can see the secret from the service settings page. The signature is added as sig parameter and is calculated as md5 checksum of the request parameters and secret concatenated together. You can make the same calculation and check whether the sig parameter in the request matches the one that you calculated. See the PHP example below to find out exactly how the calculation is made.

<?php

  //set true if you want to use script for billing reports
  //first you need to enable them in your account
  $billing_reports_enabled = false;

  // check that the request comes from Fortumo server
  if(!in_array($_SERVER['REMOTE_ADDR'],
      array('81.20.151.38', '81.20.148.122', '79.125.125.1', '209.20.83.207'))) {
    header("HTTP/1.0 403 Forbidden");
    die("Error: Unknown IP");
  }

  // check the signature
  $secret = ''; // insert your secret between ''
  if(empty($secret) || !check_signature($_GET, $secret)) {
    header("HTTP/1.0 404 Not Found");
    die("Error: Invalid signature");
  }

  $sender = $_GET['sender'];
  $message = $_GET['message'];
  $message_id = $_GET['message_id'];//unique id
  //hint:use message_id to log your messages
  //additional parameters: country, price, currency, operator, keyword, shortcode 
  // do something with $sender and $message
  $reply = "Thank you $sender for sending $message";

  // print out the reply
  echo($reply);
 
 //customize this according to your needs
  if($billing_reports_enabled 
    && preg_match("/Failed/i", $_GET['status']) 
    && preg_match("/MT/i", $_GET['billing_type'])) {
   // find message by $_GET['message_id'] and suspend it
  }


  function check_signature($params_array, $secret) {
    ksort($params_array);

    $str = '';
    foreach ($params_array as $k=>$v) {
      if($k != 'sig') {
        $str .= "$k=$v";
      }
    }
    $str .= $secret;
    $signature = md5($str);

    return ($params_array['sig'] == $signature);
  }
?>

Copy to clipboard