Payment notifications

When someone completes a payment, Fortumo will inform service providers’ servers by making a HTTP GET request to the URL that was specified in the service configuration (for example https://yourdomain.com/in-app-payment.php). The payment processor can be written in any server side technology including .NET, Java, Ruby on Rails. This response is considered successful and notification delivered if your server responds with code 200. In case your server fails to respond with HTTP 200, notification sending is retried up to 15 times with growing intervals.

Receipt verification is a convenient way for integrating in-app purchases with users online profile so that in-app purchases can be kept track of and shared between different devices and platforms.

Receipt verification can also be used to gather live statistics about purchases made and integrate data with your live dashboard or accounting systems.

Notification parameters

Parameter Type Required Description
service_id String Mandatory 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. Example: f7fa12b381d290e268f99e382578d64a
price Float, 2 decimals Mandatory The end user price of the message in the local currency, including VAT. Example: 2.00/0.99
currency String, ISO 4217 Mandatory The local currency symbol according to ISO 4217(more codes). Example: EUR, SEK, NOK, USD, GBP etc
credit_amount Integer Optional Currency amount, only for virtual currency services. Example: 256
credit_name String Optional Currency name, only for virtual currency services. Example: gold coins
product_name String Mandatory Description of the product the user is paying for. Max 32 characters. May include A-Za-z0-9 and also "_" and "-" symbols. Example: user123-magicPotion, almighty-sword, etd. This value is used for restoring purchases.
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. Example: EE, SE. Please also note that this is NOT necessarily the actual location of the sender. If the sender with a Swedish operator SIM could be sending a message while being roaming in Norway and you would still have SE in the country field.
operator String Mandatory Operator name. Example: Vodafone, Telefonica, Telenor
billing_type String Mandatory Can be MO, MT or DCB. 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. With MT-billing (Mobile Terminating Billing), the end-user is charged for receiving a message. DCB is direct carrier billing where the final payment status will be received instantly. Example: MO, MT or DCB
user_id String Mandatory A unique end-user identification string generated by the Android SDK from the mobile application point of view (internal SIM card identification). Example: 33445566778899
sender String Mandatory Phone number (string). Example: 37256455115 or #a2001sdf1993fc7
message_id String Mandatory Unique billing transaction id. Example: dc06a486787906f4b88dc74740f82c99
payment_code String Mandatory An unique payment identifier generated by the Fortumo payment dialogue. Example: 123456789
user_share Float, 2 decimals Mandatory Merchant share % from the transaction. Example: 0.75
price_wo_vat Float, 2 decimals Mandatory End-user price in local currency without VAT (Value Added Tax). Example: 0.27
status String Mandatory Payment status. Example: pending/ok/failed
test Boolean Optional This parameter is present only when message is sent through Fortumo testing interface by yourself and it's value is always 'true'. Example: ok/failed/sandbox
sig String Mandatory Request signature that you may check, to make sure the request is originating from Fortumo. Example: d6bc8d614c89f25935e6e8e4e82ef386

Processing the receipt verification request

The following example Receipt Verification script (hosted at your service back end) is called whenever an user makes a payment. 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['product_name'] and $_GET['status'] parameters and grants virtual items to the user who made the purchase.

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

$product_name = $_GET['product_name'];
$billing_status = $_GET['status'];
$message_id = $_GET['message_id'];//unique id

// print out the reply
echo($reply);

// only grant virtual credits to account, if payment has been successful.
if (($_GET['billing_type'] == 'MO' and $_GET['status'] == 'pending') or (in_array($_GET['billing_type'], array('MT', 'CC', 'DCB')) and $_GET['status'] == 'OK')) {
   add_credits(user_by_product_name($product_name), $_GET['credit_amount']);
}

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

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?