Payment result processing

When setting up the PSMS API service, you define a URL where a HTTP GET request with payment information is made every time a payment is made or billing status of the message changes.

Response parameters

The content of the request Fortumo makes to the URL you specified during the service setup will contain the following parameters.

Parameter Type Required Description
message String Mandatory Message content minus keywords. The parameter is empty if there was only the keyword and no additional text in the message. Example: If the message was TXT KEY 123, then this parameter is 123.
sender String Mandatory Message sender's phone number in international format without the plus sign. In some countries, due to end-user privacy protection rules, this parameter may be blank or encrypted by mobile operator. Example: 4560123456 or 358401234567.
country String, ISO Alpha-2 Mandatory 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 etc). Please also note that this is NOT necessarily the actual location of the sender. Example:SE
price Float, 2 decimals Mandatory End-user price in local currency, including VAT. Example: 0.32
price_wo_vat Float, 2 decimals Mandatory End-user price in local currency without VAT. Example: 0.27
currency String, ISO 4217 Mandatory The local currency symbol according to ISO 4217. (Country code listing). Example: EUR
service_id String Mandatory A string that identifies this Fortumo service. If you have many services with the same URL, then you can use this field to determine which service the message is for. Example: f7fa12b381d290e268f99e382578d64a
message_id String Mandatory A string that is unique for each message that your service receives. Example: 123456
keyword String Mandatory The keyword part of the message. Example: If the message was TXT KEY 123, then this parameter is TXT KEY
shortcode Integer Mandatory The short code that the message was sent to. Example: 1311
operator String Mandatory Name of the sender's mobile network operator. Example: Vodafone
billing_type String Mandatory MO and MT billing are the two methods how carriers charge users. With MO-billing (Mobile Originating Billing), the end-user is charged for sending a message, thus the billing status is checked before the request to service back end. Read more about billing types in Fortumo FAQ. Example: MO or MT
status String Mandatory Billing status, which is either pending(in message delivery request), ok or failed(in billing report). Example: ok/pending/failed
test Boolean Optional This parameter is present only when message is sent through Fortumo testing interface by yourself. Example: true
sig String Mandatory Request signature that you may check, to make sure the request is originating from Fortumo. See below under Security to find out how. Only message and sender parameters are needed to process credits to end-user. Example: 2d7b58632d855bf031af5066761f25cd
Payment in sandbox mode:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "status": "pending",
  "service_id": "0bb1f182862ec106563e017006da7f80",
  "country": "EE",
  "sender": "0000",
  "message": "Enjoy your service!",
  "currency": "EUR",
  "price_wo_vat": "0.53",
  "billing_type": "MO",
  "keyword": "TELLI MAKSA",
  "shortcode": "13011",
  "test": "true",
  "price": "0.64",
  "sig": "51376be3ab5a714f108fc6973c0a92f8",
  "message_id": "c0a4336f43f787e1e05f72fe9f0d253a",
  "operator": "Tele2"
}
Succesful MO billing in live:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "status": "pending",
  "service_id": "0bb1f182862ec106563e017006da7f80",
  "country": "EE",
  "sender": "37255555555",
  "message": "Enjoy your service!",
  "currency": "EUR",
  "price_wo_vat": "0.53",
  "billing_type": "MO",
  "keyword": "TELLI MAKSA",
  "shortcode": "13011",
  "price": "0.64",
  "sig": "51376be3ab5a714f108fc6973c0a92f8",
  "message_id": "c0a4336f43f787e1e05f72fe9f0d421",
  "operator": "Tele2"
}
Succesful MT payment in live:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "status": "ok",
  "service_id": "0bb1f182862ec106563e017006da7f80",
  "country": "EE",
  "sender": "37255555555",
  "message": "Enjoy your service!",
  "currency": "EUR",
  "price_wo_vat": "0.53",
  "billing_type": "MT",
  "keyword": "TELLI MAKSA",
  "shortcode": "13011",
  "price": "0.64",
  "sig": "51376be3ab5a714f108fc6973c0a92f8",
  "message_id": "c0a4336f43f787e1e05f72fe9f0d421",
  "operator": "Tele2"
}
Failed MO billing in live:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "status": "failed",
  "currency": "ARS",
  "keyword": "FOR WCOSCOIN",
  "service_id": "0ed26d80426ee588f925d90480d4d974",
  "billing_type": "MO",
  "country": "AR",
  "message": "49381912",
  "message_id": "c0a4336f43f787e1e05f72fe9fs5ei23",
  "sig": "51376be3ab5a714f108fc6973c0a9asd",
  "sender": "541161111112",
  "operator": "Personal",
  "price_wo_vat": "11.19",
  "shortcode": "22533",
  "price": "14.01"
}
Failed MT payment in live:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "status": "Failed",
    "currency": "HRK",
    "keyword": "TXT15 WCOSCOIN",
    "service_id": "0ed26d80426ee588f925d90489e7g374",
    "billing_type": "MT",
    "country": "HR",
    "message": "49012930",
    "message_id": "c2075e27f2320f12e2534fkd92e2b7fa",
    "sig": "a62090f262834d894b3c567e044e273c",
    "sender": "00385997777771",
    "operator": "Hrvatski Telekom",
    "price_wo_vat": "12.0",
    "shortcode": "866866",
    "price": "15.0"
}

Sample script

The following PHP script is called whenever an user makes a payment (hosted at your service back end). The script first makes security checks (validate IP addresses, check the signature) to validate that the request came from Fortumo. Then the script processes the $_GET['message'] and $_GET['sender'] parameters and creates a response that will be sent to the users phone.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
<?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('1.2.3.4', '2.3.4.5'))) {
    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);

// only grant virtual credits to account, if payment has been successful.
 if(preg_match("/OK/i", $_GET['status'])
    || (preg_match("/MO/i", $_GET['billing_type']) && preg_match("/pending/i", $_GET['status']))) {
     add_credits($message);
  }

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

Details about security and signature

Since Fortumo handles monetary values, there are security measures to protect merchants and end-users interests, at the same time maintaining payment process usability. Details on security page.

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