Fortumo Mobile Payments API Integration Guideline

Version 3.5.3

2011

Fortumo Integration Guideline

Contents
1. Introduction ............................................................................................................................................................... 3 2. Setting Up a Service ................................................................................................................................................... 3 3. Technical Implementation ......................................................................................................................................... 3 3.1. Message Delivery Request.................................................................................................................................. 4 3.2. Billing Report Request (optional) ....................................................................................................................... 5 3.3. MO and MT Billing Types .................................................................................................................................... 5 3.4. Testing Your Script .............................................................................................................................................. 5 3.5. Security ............................................................................................................................................................... 5 4. Service Approval ........................................................................................................................................................ 6 5. Promotional Information ........................................................................................................................................... 6 6. Billing Model Examples.............................................................................................................................................. 7 Example 1: Online Game Credits, Single Interaction ................................................................................................. 7 Example 2: Double Interaction .................................................................................................................................. 7 7. XML File Example ....................................................................................................................................................... 8

Fortumo Integration Guideline

1. Introduction
Founded in 2007 and with offices in Europe and Silicon Valley, Fortumo is an open mobile payment platform, currently operating in more than 40 countries worldwide. We allow virtual goods providers, social networks, app developers, online and offline businesses to better monetize their users. With Fortumo, everyone can launch revenue-generating mobile payment service instantly and without any startup or monthly costs. Mobile Payments API is the most flexible service type in Fortumo. Interaction between our server and your application will be conducted with HTTP GET requests. This solution gives your application a full control over the billing interface and reply messages content allowing you to integrate Fortumo mobile payments with your existing systems or even resell it as a white-label service. This document intends to introduce the basic rules to integrate Fortumo Mobile Payments API with your service.

2. Setting Up a Service
In order to start the implementation, the following steps should be completed: 1. Create a Fortumo account 2. Start a new Mobile Payments API service 3. Select the countries and follow the service creation wizard (define prices and keywords) Try to select a simple and short keyword, for example WAW or DAD. It minimizes the chance of input errors. 4. Name your service and provide us with URLs of the scripts that will handle incoming message delivery requests (request processor) and billing reports (billing report processor, see technical info below) 5. Insert required promotional information and confirm your info 6. For countries that require operators approval, provide a link to marketing materials or skip this step (see approval info below) 7. Deploy required marketing and pricing information either by hand or using XML (see XML info below) Please note, that you can create as many services as you want and they can be updated later.

3. Technical Implementation
The whole process of handling a Fortumo mobile payment is simple. When your service receives a message, Fortumo will make a request to the request processor URL that you have specified during service configuration. The content that Fortumo receives from your script is then sent back to the user as a reply message. Optionally, if you have enabled billing reports and they are available for the particular country, Fortumo will make a request to the billing report processor with the status on the current payment.

Fortumo Integration Guideline

3.1. Message Delivery Request

When your service receives a message, Fortumo will make an HTTP GET request to the URL that you have specified in the service configuration. The content that Fortumo receives from your URL (the first 120 characters) is then sent back to the user as a reply message. The parameters of that HTTP GET request are described in the following table. Parameter keyword message Description The keyword part of the message Message content excluding the keywords Senders phone number The ISO 3166-1 country code of the sender's mobile operator Und user price of the message The local currency symbol according to ISO 4217 ID of the Fortumo service ID of the message The short code that the message was sent to Sender's mobile operator MO or MT Billing status Test request Request signature hash Read more about billing types below. Can be pending in message delivery requests and ok or failed in billing reports. Parameter is present only when message is sent through Fortumo testing interface and the value is always true. Request signature to make sure the request is originating from Fortumo, for example d6bc8d614c89f25935e6e8e4e82ef386 (see security info below) Comment If the message was TXT KEY 123, then this parameter is TXT KEY. 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. For example 4560123456 or 358401234567. Please note, that some operators do not send the actual number due to anti spam policies. For example SE for Sweden, FI Finland etc (more codes). Please also note that this is not necessarily the actual location of the sender. A Swedish phone while being roaming in Norway would still result in SE in the country field. Local currency including VAT. For example EUR, SEK, NOK, USD, GBP etc (more codes)

sender country

price currency

service_id message_id shortcode operator billing_type status test sig

For example f7fa12b381d290e268f99e382578d64a. A string that is unique for each message that your service receives, for example 5e64aaca0160cd0e17321cf208861aa5

Fortumo Integration Guideline

3.2. Billing Report Request (optional)

In countries with MT billing operators report if billing was successful or failed upon reply message delivery attempt. If you wish to receive this information, you should enable billing reports in your API service configuration and provide a report processor URL. The parameters of the billing report request are the same as with the message delivery request except that status will be either ok or failed. Most of the billing report requests are delivered within in 1-5 seconds after the message delivery reports. However, some operators (e.g. Maxis in Malaysia) do not support real-time reports and might take up to one day for the billing status to be delivered. We will send you a billing report after the message delivery. Any answer from your script will be counted as successful delivery. Your answer to billing report is not going to be forwarded to operator, so you can't use billing reports request to deliver reply message.

3.3. MO and MT Billing Types

MO and MT billing are the two methods how carriers charge users. With MO-billing (Mobile Originating Billing), operators charge for the sent message. In this case, users are billed at the moment when they sent out SMS. With MT-billing (Mobile Terminating Billing), operators charge for the reply-message sent back to the user. In this case, users are billed only when they receive the reply-message (also known as reverse billing). Different countries offer different billing systems so please check your targeted country for exact info.

3.4. Testing Your Script

Your account has a built-in testing functionality. After configuring your script's URL in your account, you can go to "Test" tab and initiate a test request from our server to your script. The parameter test will be present in test request and set to true.

3.5. Security
It is important to make sure that the service script is called by Fortumo and not by someone else. There are several security measures that satisfy most of the service providers: a) Check that the attached signature matches. All the requests are signed with the shared secret key only known to you and Fortumo. You can see the secret key from the service description page. The signature is added as sig parameter and is calculated as md5 checksum of all request parameter key=value pairs and secret key, concatenated together. You can make the same calculation and check whether the sig parameter in the request matches the one that youve calculated. Example of the concatenated string for a test request: billing_type=country=LVcurrency=LVLkeyword=TXT SERVICEmessage=testmessage_id=4fdbdfc0515b4c1297135f1d43935e5coperator=price=0.36sender=37256455 116service_id=5e64aaca0160cd0e17321cf208861aa5shortcode=1897status=pendingtest=true

Fortumo Integration Guideline

b) Check whether the IP address of the server making the request belongs to one of Fortumo's servers. Our current IP addresses are 209.20.83.207, 79.125.125.1, 81.20.151.38 and 81.20.148.122. We will let you know by e-mail when they change. Usually you can use REMOTE_ADDR variable for that. c) 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

4. Service Approval
In some of the countries mobile operators require manual approval for all new services. After creating a service, you will be asked to provide a link to promotional materials. This can be either a link to service description page or a screenshot of the page, where service shortcode and message price are presented. Please pay attention to pricing info and additional text requirements as there are different rules for every country. An example of the correct presentation can be found in the dashboard under the Setup tab. Please do not request approval if you are only testing the service and your service description is not yet ready. This can be done any time later.

5. Promotional Information
When the technical implementation is successfully completed, its time to deploy information about message prices, shortcodes etc. If you plan to start in a limited number of countries, its easier to copy the info by hand. In that case every services promotional info can be found under the Setup tab. For multi-country services with wide international coverage its recommended to take advantage of Fortumos XML export system. This way promotional materials will be perfectly integrated with your design and will always remain up to date (provided that you use the latest version of the XML file and update it daily). Every service has its own unique XML file link, which can be found under the Setup tab. A simplified example of the XML file is attached to this Integration Guideline. An example of the XML file link: http://api.fortumo.com/api/services/2/34b...a39/d23....c22.xml Sometimes shortcodes, prices or other information can change and you will need to update the promotional information. In that case Fortumo will inform you by email, all XML files will be updated automatically.

Fortumo Integration Guideline

6. Billing Model Examples

There are two common models to implement your billing service on Fortumo.

Example 1: Online Game Credits, Single Interaction

a) The keywords would consist of service keyword + account name, for instance TXT CRED username b) The first 2 keywords TXT CRED identify the service c) The 3rd keyword username is the message body, which will be available in the message parameter d) Your application processes the message parameter and returns a reply message text either in customized format or a unified message such as "We have received your message. The credit will be added to your account shortly after". e) If billing reports are enabled, Fortumo updates the billing status to your script again via the billing status request. f) Your system adds the credits to users account.

Example 2: Double Interaction

Requests are replied with a unique PIN code, which should be entered by the user. In most cases, users only receive the reply message while the billing is successful. This way only billed messages will receive the service and the keyword combination is shorter compared to first example. a) The keywords would consist of service keyword only, for instance TXT CRED b) Your application would generate and store a unique PIN, valid for a limited amount of time. c) The PIN would be sent to the user inside the reply message. d) User enters the pin code back to the web page and completes the transaction.

Fortumo Integration Guideline

7. XML File Example

<?xml version="1.0" encoding="UTF-8"?> <services_api_response version="2.0"> <status> <code>0</code> <message>OK</message> </status> <service id="8edae35a2857e5e16fd3684ad8adcc5e"> <countries> <country name="France" vat="19.60" approved="true" code="FR"> <prices> <price amount="0.35" vat_included="true" all_operators="true" currency="EUR"> <message_profile double_confirmation_shortcode="89000" shortcode="89000" double_confirmation_text="YES" keyword="TXT TEST" all_operators="true"/> <operator revenue="0.15" name="Bouygues" billing_type="MT" default_billing_status="Failed" code="Bouygues"/> <operator revenue="0.15" name="Orange" billing_type="MT" default_billing_status="Failed" code="Orange"/> <operator revenue="0.15" name="SFR" billing_type="MT" default_billing_status="Failed" code="SFR"/> </message_profile> </price> </prices> <promotional_text> <local>Prix </local> <english>Price </english> </promotional_text> </country> <country name="Belarus" vat="18.00" approved="true" code="BY"> <prices> <price amount="2500.00" vat_included="false" all_operators="false" currency="BYR"> <message_profile shortcode="3338" keyword="TXT TEST" all_operators="false"> <operator revenue="700.00" name="&#1052;&#1058;&#1057;" billing_type="MO" default_billing_status="OK" code="&#1052;&#1058;&#1057;"/> </message_profile> </price> <price amount="2900.00" vat_included="false" all_operators="false" currency="BYR"> <message_profile shortcode="3338" keyword="TXT TEST" all_operators="false"> <operator revenue="812.00 name="life:)" billing_type="MO" default_billing_status="OK" code="life:)"/> <operator revenue="812.00 name="Diallog" billing_type="MO" default_billing_status="OK" code="Diallog"/> <operator revenue="812.00 name="Velcom" billing_type="MO" default_billing_status="OK" code="Velcom"/> </message_profile> </price> </prices> <promotional_text> <local></local> <english></english> </promotional_text> </country> </countries> </service> </services_api_response>