WebAPI/WebPaymentProvider: Difference between revisions

   readonly attribute iccId;

   readonly attribute mcc;

   readonly attribute mnc;

The payment provider might need to locate the customer in order to allow or not payments depending on its region. In order to facilitate this, the mozPaymentProvider API exposes the device's SIM [http://en.wikipedia.org/wiki/Mobile_country_code MCC and MNC].

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.  

The mozPaymentProvider 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>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.

A example flow for an '''SMS MO + SMS MT''' scenario with a fake 123 charge free 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.

In order to allow the payment provider to control the behavior of the payment window, the mozPaymentProvider API exposes paymentSuccess and paymentFailed. These functions should be called by the payment provider to finish the payment flow. Both functions would close the payment flow window and trigger the [https://developer.mozilla.org/en-US/docs/DOM/DOMRequest.onsuccess onsuccess] or [https://developer.mozilla.org/en-US/docs/DOM/DOMRequest.onerror onerror] events over the [https://developer.mozilla.org/en-US/docs/DOM/DOMRequest DOMRequest] returned by the <code>navigator.mozPay</code> call. The <code>aResult</code> and <code>aErrorMsg</code> strings passed by the payment provider would be available for the application as [https://developer.mozilla.org/en-US/docs/DOM/DOMRequest.result DOMRequest.result] and [https://developer.mozilla.org/en-US/docs/DOM/DOMRequest.error DOMRequest.error] values respectively.