Fortumo Mobile Payments / Premium SMS API technical specification

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.

<?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', '209.20.83.207'))) {
    die("Error: Unknown IP");
  }

  // check the signature
  $secret = ''; // insert your secret between ''
  if(!empty($secret) && !check_signature($_GET, $secret)) {
    die("Error: Invalid signature");
  }

  $sender = $_GET['sender'];
  $message = $_GET['message'];

  // 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);
  }
?>