Proposal: Direct Billing API for mobile payments

Web API to charge payments to a customer's operator bill more easily.

Proposers

Kumar McMillan, Jonas Sicking

Status

This is a draft of a proposal. Nothing has been implemented yet.

NOTE: also see the Mobile Identity API and MSISDN Verification API.

High Level Use Case

A user is playing an adventure game on a mobile device. The game offers a Magical Unicorn for 0,89 EUR that lets them play the game in a more majestic way. The user begins payment but does not want to enter a credit card number. The user wants to tap a button that will charge their operator bill instantly and let them continue playing the game. The setup and payment flow should be as quick and seamless as possible.

Rationale

We have navigator.mozPay() and an associated WebPaymentProvider API for direct billing but they require implementers to follow a strict end-to-end JSON Web Token flow. This alternate API will expose just the direct billing primitives needed. It will not prescribe how to use them.

Access Control

Because there are too many sensitive APIs in here, only trusted web content can access this API. Access will be whitelisted by domain. No other web content will have access to this API. TBD: do we need to require a new window for that to work?

When thinking of a way to allow open access to these APIs, these are some problems we ran into:

• Arbitrary web content cannot a send silent SMS because it could charge users money
• If we whitelist short codes (which are free of charge) per operator/region then there is potential for abuse: web content could maliciously hit a short code which would cost the payment provider money
• mcc/mnc expose the user's location and network which is a privacy concern
• iccIDs can be used for fingerprinting
• It may not be possible to prompt the user to grant access in a meaningful way
• Standard app permissions do not apply because payments is a service offered to the users of apps. The app itself is not the one that needs permission.

API

interface mozDirectBilling
{
  /**
   * Send an 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 WebSMS API.
   * The number must be a short code that does not charge the user.
   */
  DOMRequest sendSilentSms(in DOMString number, in DOMString message);
  
  /**
   * Intercept any incoming MT (mobile terminated) SMS sent from the given number.
   * The number must be a short code that does not charge the user.
   */
  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);
  
  /**
   * 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;
}

Silent SMS Example

Here's an example flow for an SMS MO (mobile originated) + SMS MT (mobile terminated) scenario with a fake 123 charge free short code:

• 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 mozDirectBilling.observeSilentSms('123', onmessage);, where onmessage 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 var req = mozDirectBilling.sendSilentSms('123', uuid);. Where uuid 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 req variable returned by sendSilentSms is an instance of DOMRequest and allows the payment provider to check if the SMS is successfully sent or not.

• The message sent in the previous step is received by the short code application (on the carrier's side), which identifies the user as the sender of the SMS. The short code application sends back a message containing the uuid to the number of the sender of the previous message.

• The message sent by the short code application is intercepted by the payment provider and handled within the callback given to mozDirectBilling.observeSilentSms in the first step. If the uuid is correct, the payment provider knows that the user is properly authenticated by the carrier side and so it can continue with the payment process.

• At this point, the payment provider should do its clean up for the uuid identifying the authentication flow. It can also call mozDirectBilling.removeSilentSmsObserver, but as mentioned above, it is not mandatory.

An SMS MO (mobile originated) only flow is quite simpler and only requires a call to mozDirectBilling.sendSilentSms.

mozDirectBilling.iccIds example

A payment provider typically sets up direct billing with SMS. After it's set up the provider can enable payments over WiFi by storing a cookie on device. The iccIds can be used to know when a SIM card is swapped so that the cookie can be deleted.

mozDirectBilling.mcc and mozDirectBilling.mnc example

In order to show the user a correct price for their region, the payment provider can use the mcc and mnc codes. These codes can also be used to enable/disable specific regions when payments are not supported or still in development.