Professional Documents
Culture Documents
Version 3.5.3
2011
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
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.
sender country
price currency
For example f7fa12b381d290e268f99e382578d64a. A string that is unique for each message that your service receives, for example 5e64aaca0160cd0e17321cf208861aa5
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
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.