WebAPI/WebPaymentProvider

Overview

This is the provider specification for supporting the WebPayment API. A provider is responsible for the web pages that enable the buy flow behind navigator.mozPay() when initiated on a device. At a high level, this is what a payment provider does:

• Serve a payment confirmation screen at a custom URL in this format: https://<ANY_URI>?req=<JWT>
• Verify the incoming JWT signature
• Present product and price details (extracted from the JWT) for confirmation
• When payment processing is finished, call window.paymentSuccess() or window.paymentError()
• Send server notifications to the merchant

The purpose of this document is to show how someone could implement a provider to hook into navigator.mozPay(). 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).

Invocation

• When an app triggers an in-app payment or when a marketplace triggers an app purchase, it invokes navigator.mozPay() in JavaScript with a JWT (JSON Web Token).
• A window opens up on the customer’s device to a URL of the payment provider. This URL is determined by the typ field of the JWT but must also be in a special whitelist on the phone. All new payment providers must work with Mozilla to have their URLs added to the whitelist that is shipped with devices.
• The user agent makes a GET request to the payment provider to load the payment screen. The URL looks like this: https://paymentprovider.com/mozpay?req=<JWT>
• See the WebPayment API for details on the acceptable JWT parameters.

JWT Verification

• Before proceeding with any payment processing, the payment provider must verify the signature of the JWT (passed in as query string parameter req) so that it knows the authorized app truly requested the payment.
• 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.

Payment Confirmation

The JWT contains name, description, prices in various countries, and a suggestion for the what the customer’s default price would be. The payment provider must present this information in a clear and concise way so that the customer knows exactly what she is about to buy.

Payment Processing

When the customer clicks a button to complete payment, the provider can charge the customer for the amount of money in the selected currency. The payment provider would then dispatch the money to the merchant.

Completion

The navigator.mozPay() implementation injects two callbacks as global functions within the payment provider's web page context.

function paymentSuccess(aResult) {};

function paymentFailed(aErrorMsg) {};

where aResult and aErrorMsg are simple strings.

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 onsuccess or onerror events over the DOMRequest returned by the navigator.mozPay call. The aResult and aErrorMsg strings passed by the payment provider would be available for the application as DOMRequest.result and DOMRequest.error values respectively.

• The success callback in the app is to say “the payment is done processing.” It does not guarantee a positive or negative outcome.
• The error callback is to indicate that the processing was cancelled or aborted somehow. The specific error code details are to be decided.

Cancellation

If the customer cancels the payment by closing the window or clicking a cancel button, the payment provider must call window.paymentError() as described above.

Notifications

• When the payment processing is finished, the payment provider must send a POST to either a postback URL or chargeback URL of the app. The app developer must register these URLs with the payment provider before making calls to navigator.mozPay() or it can specify the callback URLs in the JWT that is passed into navigator.mozPay().
• The payment provider signs a JWT with the same shared secret as with invocation and POSTs this to either the postback or chargeback URL. The POST must only include the JWT in its payload.
• The JWT must include the original request as well as an additional response object that specifies the payment provider’s transaction ID.
• When a payment is successful, the notification is sent to the postback URL.
• When a payment is unsuccessful, the notification is sent the chargeback URL.
• The app must respond to the POST with a 200 OK status and must return a plain text response of the transaction ID.
• If the app server does not respond with a 200, the notification should be retried a few times and stored in a queue if the request never goes through.

See the WebPayment API for detailed examples of postback / chargeback notification JWTs.

Out of Scope

As you can see, the navigator.mozPay() API leaves a lot of implementation and user experience design up to the provider. Here are some out of scope items that are important things to consider when implementing a payment provider.

Merchant Setup

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 merchant can register default postback / chargeback URLs with the payment provider. These are used for notifications that are defined up above.

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

It's a good idea to prompt the user for a PIN code (personal identification number) or something similar at the time of payment to prevent someone from picking up the phone and immediately making payments. A customer would need to set up a PIN in advance.