Future Pay MCB API Version 03 2014-02-11
Contents Contents... 2 1. Document history... 3 2. Scope and intended audience... 3 3. Communication with Future Pay... 4 3.1 overview... 4 3.2 Request... 6 3.3 Response... 6 4. One Time Payment... 7 4.1 Request: (see 3.2 Request) Requesttype=single... 7 4.2 Response parameters on <returnurl>... 7 4.3 Response parameters on <errorurl>... 7 5. Start Subscription... 7 5.1 Request: (see 3.2 Request) Requesttype=start... 7 5.2 Response parameters on <returnurl>... 8 5.3 Response parameters on <errorurl>... 8 6. Stop Subscription... 9 6.1 Request: (see 3.2 Request) Requesttype=stop... 9 6.2 Response... 9 7. Check Subscription... 10 7.1 Request: (see 3.2 Request) Requesttype=check... 10 7.2 Response... 10 8. Identification... 11 8.1 Request: (see 3.2 Request) Requesttype=identify... 11 8.2 Respons... 11 9. Notification... 11 9.1 Start... 11 9.2 Charge... 11 9.3 Stop... 12 10. Statuscodes... 13 11. hmac calculation... 14 12. Graphical examples... 15 12.1 start redir... 15 2
12.2 stop http... 16 1. Document history date author vs changes 2013-02-15 KB, BGT 01 Country specific information separated from generic info 2013-06-11 KB 02 Added new statuscodes, Returnurl, Errorurl and Notificationurl increase in length 2014-02-11 KB 03 Added Single for one time payments 2. Scope and intended audience This document describes the communication interface and operation of the FuturePay Mobile Content Billing platform from a technicians perspective. This document is meant for the systemintegrator dealing with connecting this billing platform to his own system. Due to technical implications of national regulations and procedures, this document is to be used in conjunction with National appendices. These appendices can be found in the clients own ControlPanel, see last paragraph of next chapter. 3
3. Communication with Future Pay 3.1 overview The FuturePay platform can be reached using the url: http://futurepay.globway.eu/mcb/in This might be done using HTTP-GET or HTTP-POST. HTTP-parameters must be added by the client to describe what operation is expected from the FuturePay platform. Basically, FuturePay recognizes three HTTP-parameter-settings; start, stop and check, and sees this as three different function calls. The client-application and must interpret the response and decide upon information found here, what to do next. The response after calling above url will contain the parameters summed up in section 3.3 Response. In particular, upon success (statuscode=0), the response will contain an unique url. The client is supposed to call to, or to redirect his site-visitor to this unique url. Wether this should be a call (for instance using a curl-library or a HTTP-object) or redirect is stated by FuturePay in the parameter urlcall. If the statuscode in the response is other than zero, the client might want to check the value against the table in section 10. Statuscodes. A National appendix can dictate additional mandatory as well as additional optional parameters. Responses can have additional fields too. Due to the nature of Mobile Content Billing, the FuturePay platform sometimes will be called from the client platform and sometimes from the mobile device of the enduser. For identification of the enduser, his mobile is diverted to urls which sometimes are below the horizon of the FuturePay platform. After this dialog between mobile device on one side and FuturePay and mobile providers on the other side, FuturePay will have the mobile device callback to client-configurated urls (<errorurl> and <returnurl>) to transmit the outcome of this identification process. These callbacks will contain information using parameter-value pairs. Also, FuturePay supports asynchronous notifications. The table below describes the response the client application can expect from FuturePay. If the response after calling/redir to url will be: with parameters: urlcall=http Synchronous xml-formatted urlcall=redir Asynchronous (response is a callback) in HTTP-GET-format notification Asynchronous in HTTP-GET-format Every response and every notification contains a rid (Request ID). The rid-value in a synchronous response can be stored by the client to match is with a future asynchronous 4
response or notification. Some notifications will have a rid that does not match any rid in whatever synchronous response. Notifications with such a rid are the result of events unsollicitated by the client (you). Examples of this, are 1: notifications of charge as subscription-charges are done by FuturePay, and 2: notifications of stop after an enduser triggers this stop via a website. Moreover, every asynchronous response contains a hmac-value. This value is the result of a well-known algorithm that takes all parameters of the response as well as a secret key that is only known by FuturePay and the client. This renders the response to be less vulnerable for hacking attempts. An chapter in this manuals gives more information and examples about this algorithm and its use. Clients are able to check the authentity of the parameter values and so prevent costly content to be supplied to not-paying endusers. Simply put the parameters that FuturePay provides in its responses into the hmac-function and check the outcome against the value of the hmac-parameter. From the xml blocks given by FuturePay, clients must take the information contained in the <FP>-tag. See examples. FuturePay performs async requests from ip-addresses: 37.34.50.29 81.173.113.14 81.173.113.15 141.138.137.181 Clients have access to the FuturePay ControlPanel via url: https://futurepay.globway.eu This ControlPanel enables you to configure several settings. Instead of describing every feature of this piece of software, look around and see what parameters you yourself may read, edit and add. 5
3.2 Request Future Pay url : 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 single: one time payment start: start a subscription stop: stop a subscription check: get the subscription details identify: lookup if-which subscriptionid user has Optional Parameters returnurl string 1000 After a successful request, you will be redirected to the returnurl Default: as configured in Future Pay Controlpanel errorurl string 1000 After an unsuccessful request, you will be redirected to the errorurl Default: as configured in FuturePay Controlpanel Example: http://futurepay.globway.eu/mcb/in?username=alex&password=vanburen&service=fpd37 QS6&requesttype=start 3.3 Response Is in xml-format. statuscode integer See section 10. Statuscodes reason string 250 See section 10. Statuscodes urlcall enum http, redirect Http: use http request to Future Pay Redirect: use redirection to Future Pay url string 255 New request to this url Example: <?xml version="1.0" encoding="utf-8"?> <FP> 6
<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> 4. One Time Payment 4.1 Request: (see 3.2 Request) Requesttype=single Optional Parameters marketingkey string 250 Key to recognize your marketing channel Default: service The direct, synchronous response is described in section 3.3 Response. After calling/redirecting to <url>, the following parameters (sections.2 and.3) are added: 4.2 Response parameters on <returnurl> marketing key string 250 Your own given marketing key or by default service pid string 32 Unique payment id 4.3 Response parameters on <errorurl> marketingkey string 250 Your own given marketing key or by default service statuscode integer See section 10. Statuscodes 5. Start Subscription 5.1 Request: (see 3.2 Request) Requesttype=start Optional Parameters marketingkey string 250 Key to recognize your marketing channel 7
Default: service Future Pay MCB API v03 The direct, synchronous response is described in section 3.3 Response. After calling/redirecting to <url>, the following parameters (sections.2 and.3) are added: 5.2 Response parameters on <returnurl> marketing key string 250 Your own given marketing key or by default service sid string 32 Unique subscription id 5.3 Response parameters on <errorurl> marketingkey string 250 Your own given marketing key or by default service statuscode integer See section 10. Statuscodes 8
6. Stop Subscription 6.1 Request: (see 3.2 Request) Requesttype=stop Required Parameters sid string 32 Unique subscription id which one belongs to the start subscription The direct, synchronous response is described in section 3.3 Response. After calling/redirecting to <url>, the following parameter is added: 6.2 Response statuscode integer See 10. Statuscodes reason string 250 See 10. Statuscodes 9
7. Check Subscription 7.1 Request: (see 3.2 Request) Requesttype=check Required Parameters sid string 32 Unique subscription id which one belongs to the start subscription 7.2 Response statuscode integer See 10. Statuscodes reason string 250 See 10. Statuscodes rid string 32 unique request id marketingkey string 250 sid string 32 tariff integer 5 tariff in cents msisdn* string 64 mccmnc* string 8 provider code of mobile user mccmnc_payment* string 8 payment provider code of mobile user time_start datetime subscription start time time_stop* datetime subscription stop time time_charge* datetime subscription last charge time, regardless of successful or failed charge time_charge_success* datetime subscription last successful charge time * only when available and not empty 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> </FP> 10
8. Identification 8.1 Request: (see 3.2 Request) Requesttype=identify no additional parameters 8.2 Respons sid string 32 Unique subscription id 9. Notification 9.1 Start marketingkey string 250 sid string 32 tariff integer 5 tariff in cents time_start datetime subscription start time notification_type enum start, charge, stop Start: Start notification Charge: Charge notification Stop: Stop notification example: <?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> 9.2 Charge rid string 32 unique request id marketingkey string 250 pid string 32 sid string 32 11
tariff integer 5 tariff in cents msisdn* string 64 mccmnc* string 8 mccmnc_payment* string 8 time_start datetime subscription start time time_stop* datetime subscription stop time time_charge datetime subscription last charge time. Charge could be failed time_charge_success* datetime notification_type enum start, charge, stop subscription last successful charge time Start: Start notification Charge: Charge notification Stop: Stop notification statuscode integer 4 See statuscode * only when available and not empty 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> 9.3 Stop marketingkey* string 250 sid string 32 tariff integer 5 tariff in cents msisdn* string 64 mccmnc* string 8 mccmnc_payment* string 8 time_start datetime subscription start time time_stop* datetime subscription stop time time_charge datetime subscription last charge time Charge could be failed time_charge_success* datetime subscription last successful charge time 12
notification_type enum start, charge, stop Future Pay MCB API v03 Start: Start notification Charge: Charge notification Stop: Stop notification statuscode integer 4 See chapter statuscode * only when available and not empty 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> 10. Statuscodes 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 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 905 Internal server error 906 Temporary error at carrier side 907 Unspecified error 908 Payment failed 909 Billing in process 910 MS recognition failed 13
11. hmac calculation Note: the hmac calculation in FuturePay asynchronous responses is done using the parameters supplied by FuturePay itself. Parameters contained in url s given by our clients are not taken into this calculation. in 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 } 14
12. Graphical examples 12.1 start redir 15
12.2 stop http 16