WebAPI/WebPaymentProvider: Difference between revisions

MCC/MNC and Silent SMS doc WIP
(→‎Cancellation: documented new global object per https://bugzilla.mozilla.org/show_bug.cgi?id=877103)
(MCC/MNC and Silent SMS doc WIP)
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).
== API ==
interface mozPaymentProvider
{
  void paymentSuccess(in DOMString result);
  void paymentFailed(in DOMString error);
  DOMRequest sendSilentSms(in DOMString number, in DOMString message);
  void observeSilentSms(in DOMString number, in jsval callback);
  void removeSilentSmsObserver(in DOMString number, in jsval callback);
  readonly attribute iccId;
  readonly attribute mcc;
  readonly attribute mnc;
}


== Invocation ==
== Invocation ==
Line 25: Line 39:
* Since the JWT is base 64 encoded, the payment provider can first decode it and read the iss (issuer) from the JSON object.
* Since the JWT is base 64 encoded, the payment provider can first decode it and read the iss (issuer) from the JSON object.
* The JWT signature can be verified by using the shared secret that was granted to the issuer. See the Out of Scope section for how a merchant and payment provider would exchange a secret key.
* The JWT signature can be verified by using the shared secret that was granted to the issuer. See the Out of Scope section for how a merchant and payment provider would exchange a secret key.
== User localization ==
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].
== User identification ==
The payment provider will need to identify the customer in order to initiate a payment.
=== Carrier 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.
==== Silent SMS ====
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>
* <code>removeSilentSmsObserver(number, callback)</code>


== Payment Confirmation ==
== Payment Confirmation ==
Line 79: Line 115:


In order to begin making payments, a merchant and provider must exchange a secret key to sign JWTs with. The merchant will want to register their bank account details (or something) with the provider in order to get paid. The Payment Provider should be prepared to respond to compromised secrets by revoking them immediately.
In order to begin making payments, a merchant and provider must exchange a secret key to sign JWTs with. The merchant will want to register their bank account details (or something) with the provider in order to get paid. The Payment Provider should be prepared to respond to compromised secrets by revoking them immediately.
=== Identity ===
The payment provider will need to identify the customer in order to initiate payment (for example, the provider might bill the customer's mobile carrier).


=== PIN ===
=== PIN ===
Confirmed users
483

edits