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.