MCB Gateway 1 Introduction This document describes the communication interface (API) of our Mobile Content Billing (MCB/DB) gateway called FuturePay. This technical document is meant for system engineers that want to integrate Direct Billing for an online product or campaign. A national appendix can overrule or add additional mandatory as well as optional parameters required for specifc countries in requests and responses. It is an addition to this document for that specific country. 2 Change history Version Date Comment Current Version (v. 3) Jan 12, 2015 09:00 Kenneth Bhadjoe v. 2 Dec 06, 2014 10:37 Peter Paul Keulers v. 1 Oct 09, 2014 13:43 Kenneth Bhadjoe 3 Table of contents 1 Introduction 2 Change history 3 Table of contents 4 Communication 4.1 Overview 4.2 Control panel 4.3 IP addresses 4.4 Workflow 4.5 Request 4.6 Response 5 Single Payment 5.1 Request 5.2 Response parameters on returnurl 5.3 Response parameters on errorurl 6 Start Subscription 6.1 Request 6.2 Response parameters on returnurl 6.3 Response parameters on errorurl 7 Stop Subscription 7.1 Request 7.2 Response 8. Check Subscription 8.1 Request 8.2 Response 9 Identification 9.1 Request 9.2 Response 10 Asynchronous Notifications 10.1 Start notifications 10.2 Charge notification 10.3 Stop notification 11 Status codes 12 HMAC calculation 13 Graphical examples 13.1 Start workflow 13.2 Stop workflow Copyright Globway B.V. - Spoorhaven 44-46 - 2651 AV - Berkel en Rodenrijs Page 1
4 Communication 4.1 Overview The gateway can be reached using the URL below using (secure) HTTP GET and POST methods: http(s)://futurepay.globway.eu/mcb/in 4.2 Control panel Clients have access to the gateway Control Panel via URL: http(s)://admin.futurepay.globway.eu This Control Panel enables you to configure settings related to the individual services that allow you to facilitate Mobile Content Billing in a country. The most important settings you can configure are found in the table below: Parameter Return URL Error URL Notification URL Wifi URL Sms URL Description Client is returned here on successfull Payment or Subscripton Client is returned here if any error occured Asynchronous notifications, start, charge and stop Not for every country, usually refers to the MSISDN entry page Not for every country, usually refers to the PIN entry page 4.3 IP addresses The gateway performs asynchronous requests from the following IP addresses: 87.250.157.128/27 4.4 Workflow FuturePay recognizes the following request types. Requesttype single start stop check identify Desscription One TIme Payment Start a subscription Stop a subscription Get subscription info Identifying the end user, see if already subscribed The client application must interpret the response and decide what to do after performing an action. The response after calling the URL is explained in section 4.6 Response. In particular, upon success ( statuscode=0), the response will contain a unique URL. The client is supposed to call it, or redirect a visitor to this unique URL. This is dependent on the parameter urlcall contained in the response. If the statuscode in a response is not zero, this indicates an error and the client should check the value against the status codes illustrated in the table in chapter 11. Due to the nature of Mobile Content Billing, the gateway will sometimes be called from the client platform and sometimes from the mobile device of the end user. For identification of the end user, the mobile is redirected to URLs which are 'out of reach' of the FuturePay platform (most of the time this concerns redirects to operator webpages for identification purposes). Copyright Globway B.V. - Spoorhaven 44-46 - 2651 AV - Berkel en Rodenrijs Page 2
After a dialog between the mobile device of the end user and FuturePay/mobile operators on the other side, the gateway will transmit the outcome of this identification process. These callbacks will contain information using parameter-value pairs in the URL (GET). The gateway also provides asynchronous notifications. The table below describes the response the client application can expect from FuturePay. If Response after call/redirect to URL Parameters urlcall=http Synchronous XML format urlcall=redir Synchronous, redirect to the url in the response HTTP GET method notification Asynchronous HTTP GET method Every response and every notification contains an rid (Request ID). The rid in a synchronous response can be stored by the client to match future asynchronous responses or notifications. Some notifications will contain a unique rid, those notifications are the result of events that occur outside of the workflow described above. Examples are: notifications of charges for subscriptions done by the gateway (rebillings) and stop notifications if an end user triggers this stop via an external website/platform. Every asynchronous response contains an HMAC-value. This value is the result of an algorithm that takes all parameters of the response as well as a secret key that is only known by the gateway and the client. This allows verification of the parameters in a response from the gateway. Clients should check the authenticity of the parameter values in order to prevent abuse and errors when performing calls to the gateway. If the response supplied by FuturePay is an XML response clients must process all parameters contained in the <FP> -tag inside the body of the page. 4.5 Request FuturePay URL A request must be performed to the URL specified below: http://futurepay.globway.eu/mcb/in Required parameters username string 32 Client username provided by Globway password string 32 Client password provided by Globway service string 32 Application service provided by Globway requesttype enum single, start, stop, check, identify Optional parameters One time payment Start a subscription Stop a subscription Get the subscription details Lookup if-which subscription ID a visitor has returnurl string 1000 After a successful request, you will be redirected to the returnurl Default: as configured in FuturePay Control Panel errorurl string 1000 After an unsuccessful request, you will be redirected to the errorurl Example Default: as configured in FuturePay Control Panel http://futurepay.globway.eu/mcb/in?username=alex&password=vanburen&service=fpd37qs6&requesttype=start 4.6 Response The response is in XML format. Copyright Globway B.V. - Spoorhaven 44-46 - 2651 AV - Berkel en Rodenrijs Page 3
statuscode integer See section 11 Status codes reason string 250 See section 11 Status codes urlcall string http, redirect http: send http request to FuturePay redirect: redirect to FuturePay url string 255 New request to this URL Example <?xml version="1.0" encoding="utf-8"?> <FP> <statuscode>0</ statuscode> <reason>ok</ reason> <rid>r160</rid> <urlcall>http</urlcall> <url>http://futurepay.globway.eu/mcb/in/hash:50af781d-46c0-4e30-9c25-3b0dc0a85072</url> </FP> 5 Single Payment 5.1 Request Optional Parameters marketingkey string 250 Key to recognize your marketing channel Default: service The direct, synchronous response is described in section 4.6 Response. 5.2 Response parameters on returnurl The returnurl is called after a successful request. marketing key string 250 Your own given marketing key (default 'service') pid string 32 Unique payment ID 5.3 Response parameters on errorurl The errorurl is called if the request is cancelled or an error occurs. marketingkey string 250 Your own given marketing key (default 'service') statuscode integer See section 11 Status codes Copyright Globway B.V. - Spoorhaven 44-46 - 2651 AV - Berkel en Rodenrijs Page 4
6 Start Subscription This request is done to start a new subscription for a visitor. 6.1 Request Optional Parameters marketingkey string 250 Key to recognize your marketing channel Default: service The direct, synchronous response is described in section 4.6 Response. 6.2 Response parameters on returnurl The response is in XML format. marketing key string 250 Your own given marketing key (default 'service') sid string 32 Unique subscription ID 6.3 Response parameters on errorurl marketingkey string 250 Your own given marketing key (default 'service') statuscode integer See section 11 Status codes 7 Stop Subscription This request is performed to stop an active subscription for a visitor. 7.1 Request Required Parameters sid string 32 Unique subscription ID which one belongs to the start subscription The direct, synchronous response is described in section 4.6 Response. 7.2 Response Copyright Globway B.V. - Spoorhaven 44-46 - 2651 AV - Berkel en Rodenrijs Page 5
The response is in XML format. statuscode integer See 11 Status codes reason string 250 See 11 Status codes 8. Check Subscription This request is performed to check whether a visitor has an active subscription. 8.1 Request Required Parameters sid string 32 Unique subscription ID which one belongs to the start subscription 8.2 Response The response is in XML format. Parameter Type Length Optional Description statuscode integer See 11 Status codes reason string 250 See 11 Status codes marketingkey string 250 Your own given marketing key (default 'service') sid string 32 Subscription ID tariff integer 5 Tariff in cents msisdn string 64 The MSISDN of the visitor mccmnc string 8 Yes Provider code of mobile user mccmnc_payment string 8 Yes Payment provider code of mobile user time_start datetime Subscription start time time_stop datetime Yes Subscription stop time time_charge datetime Yes Subscription last charge attempt time_charge_success datetime Yes Subscription last successful charge Example Copyright Globway B.V. - Spoorhaven 44-46 - 2651 AV - Berkel en Rodenrijs Page 6
<?xml version="1.0" encoding="utf-8"?> <FP> <rid>r160</rid> <marketingkey>banner Globway</marketingkey> <sid>r320</sid> <tariff>499</tariff> <msisdn>49123456789123</msisdn> <mccmnc>26201</mccmnc> <mccmnc_payment>26201</mccmnc_payment > <time_start>2012-01-01 00:00:00</ time_start> <time_stop>2012-04-01 00:00:00</ time_stop> <time_charge>2012-03-01 00:00:00</ time_charge> <time_charge_success>2012-02-01 00:00:00</ time_charge_success> </FP> 9 Identification This request is performed to identify a visitor. 9.1 Request No additional parameters. 9.2 Response The response is in XML format. sid string 32 Unique subscription ID 10 Asynchronous Notifications These notifications are sent to the notification URL that is set for your service in the gateway. 10.1 Start notifications Parameter Type Length Optional Description marketingkey string 250 Your own given marketing key (default 'service') sid string 32 Subscription ID tariff integer 5 Tariff in cents time_start datetime Subscription start time notification_type string start Notification type: In this case 'start' Example Copyright Globway B.V. - Spoorhaven 44-46 - 2651 AV - Berkel en Rodenrijs Page 7
<?xml version="1.0" encoding="utf-8"?> <FP> <rid>r160</rid> <marketingkey>banner Globway</marketingkey> <sid>r320</sid> <tariff>499</tariff> <time_start>2012-01-01 00:00:00</ time_start> <notification_type>start</notification_type> </FP> 10.2 Charge notification Parameter Type Length Optional Description marketingkey string 250 Your own given marketing key (default 'service') pid string 32 Payment ID sid string 32 Subscription ID tariff integer 5 Tariff in cents msisdn string 64 Yes MSISDN if available mccmnc string 8 Yes Provider code of mobile user mccmnc_payment string 8 Yes Payment provider code of mobile user time_start datetime Subscription start time time_stop datetime Yes Subscription stop time time_charge datetime Subscription last charge attempt time_charge_success datetime Yes Subscription last successful charge notification_type string charge Notification type: in this case 'charge' statuscode integer 4 See 11 Status codes Example <?xml version="1.0" encoding="utf-8"?> <FP> <rid>r160</rid> <marketingkey>banner Globway</marketingkey> <sid>r320</sid> <tariff>499</tariff> <msisdn>49123456789123</msisdn> <mccmnc>26201</mccmnc> <mccmnc_payment>26201</mccmnc_payment > <time_start>2012-01-01 00:00:00</ time_start> <time_stop>2012-04-01 00:00:00</ time_stop> <time_charge>2012-03-01 00:00:00</ time_charge> <time_charge_success>2012-02-01 00:00:00</ time_charge_success> <notification_type>charge</notification_type> <statuscode>0</statuscode> </FP> 10.3 Stop notification Parameter Type Length Optional Description marketingkey string 250 Yes Your own given marketing key (default 'service') sid string 32 Subscription ID Copyright Globway B.V. - Spoorhaven 44-46 - 2651 AV - Berkel en Rodenrijs Page 8
tariff integer 5 Tariff in cents msisdn string 64 Yes MSISDN if available mccmnc string 8 Yes Provider code of mobile user mccmnc_payment string 8 Yes Payment provider code of mobile user time_start datetime Subscription start time time_stop datetime Subscription stop time time_charge datetime Subscription last charge attempt time_charge_success datetime Yes Subscription last successful charge notification_type string stop Notification type: in this case 'stop' statuscode integer 4 See chapter 11 Status codes Example <?xml version="1.0" encoding="utf-8"?> <FP> <rid>r160</rid> <marketingkey>banner Globway</marketingkey> <sid>r320</sid> <tariff>499</tariff> <msisdn>49123456789123</msisdn> <mccmnc>26201</mccmnc> <mccmnc_payment>26201</mccmnc_payment > <time_start>2012-01-01 00:00:00</ time_start> <time_stop>2012-04-01 00:00:00</ time_stop> <time_charge>2012-03-01 00:00:00</ time_charge> <time_charge_success>2012-02-01 00:00:00</ time_charge_success> <notification_type>stop</notification_type> <statuscode>0</statuscode> </FP> 11 Status codes Statuscode Reason Description 0 OK 1 [PARAMETER] Parameter is missing 2 Credentials incorrect 3 [PARAMETER VALUE] Requesttype incorrect 4 [HASH VALUE] Hash incorrect 5 Subscription not found 6 IP not allowed 7 [SERVICE VALUE] Service incorrect 99 [HTTP ERROR CODE] Technical error 900 Payment cancelled 901 Prepaid MS has not enough credit 902 MS disabled for premium services 903 Destination invalid 904 Already subscribed Copyright Globway B.V. - Spoorhaven 44-46 - 2651 AV - Berkel en Rodenrijs Page 9
905 Internal server error 906 Temporary error at carrier side 907 Unspecified error 908 Payment failed 909 Billing in process 910 MS recognition failed 12 HMAC calculation The HMAC calculation in asynchronous responses from the gateway are done using the parameters supplied by the gateway itself. Parameters supplied by the client in the URL are not included in the calculation. <?php function my_hmac($secret) { $tmp = $_GET; unset($tmp['hmac']); ksort($tmp); if (hash_hmac('sha1', http_build_query($tmp), $secret) == $_GET['hmac']) { return true; } else { return false; } } // validate a asynchronous response $secret = 'ABCDEF';//secret key supplied by FuturePay if (my_hmac($secret)) { // handle the authentic asynchronous FuturePay response } else { // handle the hack } 13 Graphical examples 13.1 Start workflow Copyright Globway B.V. - Spoorhaven 44-46 - 2651 AV - Berkel en Rodenrijs Page 10
1. End-User lands on Landing Site, Clicks on the banner/subscribe button. 2. Client performs a start request at the gateway. 3. The gateway responds with an XML response. 4. Client redrects to the URL provided by the gateway (in the response). 5. The gateway redirects the end user to the operator. 6. The operator redirects the end user back to the gateway. Note step 5 and 6 can be repeated a number of times depending on country/operator. 7. The end user lands on payment page and confirms subscription. Copyright Globway B.V. - Spoorhaven 44-46 - 2651 AV - Berkel en Rodenrijs Page 11
8. The operator redirects the end user to the gateway 9. The gateway redirects the end user to the returnurl specified by the client. 10. The client grants the user access to content. 11. Later, in an asynchronous fashion, the operator sends a notification with the new subscription information. 12. The gateway sends a start notification to the client. 13. Later, in an asynchronous fashion, the operator sends notification about charges. These are performed during the start of a subscription and for subscription rebillings. 14. The gateway sends a charge notification to the client. 13.2 Stop workflow 1. The end user lands on a website promoting a product or service for which he/she is subscribed and clicks on the unsubscribe link. 2. The client identifies the user and performs a stop request at the gateway (by communication a subscription ID). 3. The gateway gives an XML response with a URL to call. 4. The client performs a HTTP request to the specified URL. 5. The gateway performs the request to the operator. 6. The operator responds to the gateway. 7. The gateway sends an XML response to the client. 8. The operator sends a notification about the unsubscribe event. 9. The gateway sends a stop notification to the client 10. The client redirects the end user to the homepage of the product or service with a message stating the user has been unsubscribed. Copyright Globway B.V. - Spoorhaven 44-46 - 2651 AV - Berkel en Rodenrijs Page 12