How does the Pay-by-Mobile Widget work?

Pay-by-Mobile Widget is an all-in one international mobile payment solution for web-based businesses. Setting it up is Quick, Easy, and Free. It's perfect for selling credits in online games, charging for access to content, etc... Get Started Now!

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.

currency

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

amount

Amount of credits purchased

price

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

user_share

Your share of the enduser price.

cuid

A string that you have provided as an resource ID in your system. You can connect payment with particular resource (i.e user) of your system by putting its ID to the end of payment dialog URL.

payment_id

Unique identifier of payment.

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.

operator

Name of the sender's mobile network operator.

status

Payment status, which is completed for successful payment or contains the phrase failed.

test

This parameter is present only when message is sent through Fortumo testing interface and it's value is either 'ok' or 'fail'.

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
  
  // 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'];//phone num.
  $amount = $_GET['amount'];//credit
  $cuid = $_GET['cuid'];//resource i.e. user
  $payment_id = $_GET['payment_id'];//unique id

  //hint: find or create payment by payment_id
  //additional parameters: operator, price, user_share, country
  
  if(preg_match("/failed/i", $_GET['status'])) {
   // mark payment as failed
  } else {
   // mark payment successful
  }

  // print out the reply
  echo('OK');
 
  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);
  }
?>