MozillaWiki

WebAPI/WebPaymentProvider: Difference between revisions

Page Discussion

WebAPI/WebPaymentProvider (view source)

Revision as of 23:24, 1 October 2014

1,663 bytes added ,  1 October 2014
no edit summary
No edit summary
No edit summary
 
(10 intermediate revisions by one other user not shown)
Line 12: Line 12:


The purpose of this document is to show how someone could implement a provider to hook into <code>navigator.mozPay()</code>. As you will see, there are many relevant pieces to the payment provider that are important but that are out of scope for this document (summarized below).
The purpose of this document is to show how someone could implement a provider to hook into <code>navigator.mozPay()</code>. As you will see, there are many relevant pieces to the payment provider that are important but that are out of scope for this document (summarized below).
There is also a [[WebAPI/Direct_Billing|Direct Billing API proposal]] that might replace this.


== API ==
== API ==
Line 19: Line 21:
  interface mozPaymentProvider
  interface mozPaymentProvider
  {
  {
  /**
    * Close the payment window after success. The result will be returned to DOMRequest.result in [[WebAPI/WebPayment|navigator.mozPay()]].
    */
   void paymentSuccess(in DOMString result);
   void paymentSuccess(in DOMString result);
 
  /**
    * Close the payment window after failure. The result will be returned to DOMRequest.result in [[WebAPI/WebPayment|navigator.mozPay()]].
    */
   void paymentFailed(in DOMString error);
   void paymentFailed(in DOMString error);
 
  /**
    * Send an [http://en.wikipedia.org/wiki/Short_Message_Service MO (mobile originated) SMS] without storing it on the device's SMS database or requesting delivery status.
    * The SMS will not show any notifications and will not appear in any SMS application consuming the [https://wiki.mozilla.org/WebAPI/WebSMS WebSMS API].
    */
   DOMRequest sendSilentSms(in DOMString number, in DOMString message);
   DOMRequest sendSilentSms(in DOMString number, in DOMString message);
 
  /**
    * Intercept any incoming MT (mobile terminated) SMS sent from the given number.
    */
   void observeSilentSms(in DOMString number, in jsval callback);
   void observeSilentSms(in DOMString number, in jsval callback);
 
  /**
    * Remove a previously observed number and its corresponding handler.
    */
   void removeSilentSmsObserver(in DOMString number, in jsval callback);
   void removeSilentSmsObserver(in DOMString number, in jsval callback);
   readonly attribute iccId;
 
   readonly attribute mcc;
  /**
   readonly attribute mnc;
    * Array of integrated circuit card IDs that are currently active on the mobile device.
    */
   readonly attribute array iccIds;
 
  /**
    * Mobile Country Code (MCC) of the network operator
    */
   readonly attribute unsigned short mcc;
 
  /**
    * Mobile Network Code (MNC) of the network operator
    */
   readonly attribute unsigned short mnc;
  }
  }
== Multi-SIM Support ==
See [[WebAPI/WebPayment/Multi-SIM|WebPayment/Multi-SIM]]


== Invocation ==
== Invocation ==
Line 52: Line 90:
=== Mobile billing ===
=== Mobile billing ===


In order to charge a user for a purchased digital good via carrier billing, the payment provider needs to identify the user as an authenticated carrier user. The way the user is identified depends on the capabilities of the carrier's network and on the device connection status. Some carriers provide a network based authentication mechanism where the users can be identified and authenticated by IP. This mechanism requires the user's device to have an active data connection (i.e. 3G) and it obviously won't work if the user's device is connected via WiFi. The network based authentication mechanism provides a seamless UX where the user can be "silently" authenticated. However, the requirements for this authentication mechanism are unfortunately not always met, so we also need to provide fallback mechanisms as an alternative to the network based one. One of this fallbacks is the SMS flow.  
In order to charge a user for a purchased digital good via carrier billing, the payment provider needs to identify the user as an authenticated carrier user. The way the user is identified depends on the capabilities of the carrier's network and on the device connection status. Some carriers provide a network based authentication mechanism where the users can be identified and authenticated by IP. This mechanism requires the user's device to have an active data connection (i.e. 3G) and it obviously won't work if the user's device is connected via WiFi. The network based authentication mechanism provides a seamless UX where the user can be "silently" authenticated. However, the requirements for this authentication mechanism are unfortunately not always met, so we also need to provide fallback mechanisms as an alternative to the network based one. One of these fallbacks is the SMS flow.  


==== Silent SMS ====
==== Silent SMS ====
Line 58: Line 96:
The <code>mozPaymentProvider</code> API exposes three methods for allowing the payment provider to do an SMS based authentication flow.
The <code>mozPaymentProvider</code> API exposes three methods for allowing the payment provider to do an SMS based authentication flow.


* <code>sendSilentSms(number, message)</code>, which allows the payment provider to send an [http://en.wikipedia.org/wiki/Short_Message_Service MO SMS] without storing it on the device's SMS database or requesting delivery status, which means that the SMS will not show any notifications and will not appear in any SMS application consuming the [https://wiki.mozilla.org/WebAPI/WebSMS WebSMS API]. This function returns a [https://developer.mozilla.org/en-US/docs/DOM/DOMRequest DOMRequest] object so the caller can check that the SMS is successfully sent.
* <code>sendSilentSms(number, message)</code>, which allows the payment provider to send an [http://en.wikipedia.org/wiki/Short_Message_Service MO (mobile originated) SMS] without storing it on the device's SMS database or requesting delivery status, which means that the SMS will not show any notifications and will not appear in any SMS application consuming the [https://wiki.mozilla.org/WebAPI/WebSMS WebSMS API]. This function returns a [https://developer.mozilla.org/en-US/docs/DOM/DOMRequest DOMRequest] object so the caller can check that the SMS is successfully sent. The number parameter is expected to be a [http://en.wikipedia.org/wiki/Short_code short code].


* <code>observeSilentSms(number, callback)</code>, which allows to the payment provider to intercept any incoming MT SMS sent from the given number. The content of the intercepted SMS will be given to the payment provider through the callback provided as the second parameter in the form of a [https://mxr.mozilla.org/mozilla-central/source/dom/mobilemessage/interfaces/nsIDOMMozSmsMessage.idl nsIDOMMozSmsMessage] . Same as before, this means that the SMS will be shown in SMS application or notification. The SMS will be silent.
* <code>observeSilentSms(number, callback)</code>, which allows to the payment provider to intercept any incoming MT (mobile terminated) SMS sent from the given number. The content of the intercepted SMS will be given to the payment provider through the callback provided as the second parameter in the form of a [https://mxr.mozilla.org/mozilla-central/source/dom/mobilemessage/interfaces/nsIDOMMozSmsMessage.idl nsIDOMMozSmsMessage] . Same as before, this means that the SMS will be shown in SMS application or notification. The SMS will be silent. The number parameter is expected to be a [http://en.wikipedia.org/wiki/Short_code short code].


* <code>removeSilentSmsObserver(number, callback)</code>, which allows the payment provider to remove a previously observed number and its corresponding handler. This method will automatically be called with the completion of the payment flow (via 'paymentSuccess' or 'paymentFailed' calls or if the user manually closes the payment flow), so the payment provider doesn't need to do any manual clean up of the set up observers. This method is only exposed just in case the payment provider wants to remove a silent SMS observer before the completion of the whole payment flow.
* <code>removeSilentSmsObserver(number, callback)</code>, which allows the payment provider to remove a previously observed number and its corresponding handler. This method will automatically be called with the completion of the payment flow (via 'paymentSuccess' or 'paymentFailed' calls or if the user manually closes the payment flow), so the payment provider doesn't need to do any manual clean up of the set up observers. This method is only exposed just in case the payment provider wants to remove a silent SMS observer before the completion of the whole payment flow.


A example flow for an '''SMS MO + SMS MT''' scenario with a fake 123 charge free short code could be something like:
A example flow for an '''SMS MO + SMS MT''' scenario with a fake 123 charge free [http://en.wikipedia.org/wiki/Short_code short code] could be something like:


* As the payment provider will be "talking" with the short code application for 123, the first step should be start observing the messages coming from that number. This is done via <code>mozPaymentProvider.observeSilentSms('123', onmessage);</code>, where <code>onmessage</code> is the callback that will handle the reception of an SMS coming from 123.
* As the payment provider will be "talking" with the [http://en.wikipedia.org/wiki/Short_code short code] application for 123, the first step should be start observing the messages coming from that number. This is done via <code>mozPaymentProvider.observeSilentSms('123', onmessage);</code>, where <code>onmessage</code> is the callback that will handle the reception of an SMS coming from 123.


* Once it is ready to handle messages from 123, the payment provider requests to send an SMS via <code>var req = mozPaymentProvider.sendSilentSms('123', uuid);</code>. Where <code>uuid</code> is a variable containing the body of the SMS. It is recommendable to send a generated unique ID (uuid) as the message body, that will need to be sent back by the short code application, so the payment provider can match each send with its corresponding reply. The payment provider will need to keep track of these uuids and remove them as soon as a matching reply is received or after a timeout or send failure. The <code>req</code> variable returned by <code>sendSilentSms</code> is an instance of [https://developer.mozilla.org/en-US/docs/DOM/DOMRequest DOMRequest] and allows the payment provider to check if the SMS is successfully sent or not.
* Once it is ready to handle messages from 123, the payment provider requests to send an SMS via <code>var req = mozPaymentProvider.sendSilentSms('123', uuid);</code>. Where <code>uuid</code> is a variable containing the body of the SMS. It is recommendable to send a generated unique ID (uuid) as the message body, that will need to be sent back by the short code application, so the payment provider can match each send with its corresponding reply. The payment provider will need to keep track of these uuids and remove them as soon as a matching reply is received or after a timeout or send failure. The <code>req</code> variable returned by <code>sendSilentSms</code> is an instance of [https://developer.mozilla.org/en-US/docs/DOM/DOMRequest DOMRequest] and allows the payment provider to check if the SMS is successfully sent or not.
Line 128: Line 166:


Mozilla is building a web payment provider available at https://github.com/mozilla/webpay . You can install it from source at that link.
Mozilla is building a web payment provider available at https://github.com/mozilla/webpay . You can install it from source at that link.
[[Category:Web APIs]]
Chaasof
Confirmed users
1,340

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/701397...1021308"