Skip to content

How it Works

Jump to bottom
ianbjacobs edited this page Dec 15, 2015 · 13 revisions

Here we outline the different steps envisioned under this architecture.

Registration

In this model, "registration" is the process of communicating Payment App information to the Payment Mediator. At a minimum, this involves information about the Payment Methods that the Payment App supports. Depending on the deployment scenario, registration may also involve installation of software (e.g., installation of a native mobile platform payment application).

Example registration scenarios (see the group's Registration scenarios):

  • On a mobile device this may be through the mobile platform's app store.
  • On a desktop it may be through a browser API call initiated when the user visits the website of the app publisher.

In the example described below:

  • A bank has published a Payment App.
  • A bank customer has logged into the bank's Web site. The user's browser has a built-in Payment Mediator.
  • The customer also has also installed the bank's native mobile app.

The customer visiting the bank's Web site registers the Payment App. The registration API call to the Payment Mediator might look something like this:

navigator.payments.registerPaymentApp({
    "id" : "https://mybank.com/app/" //Some debate around this property. See Issue #14
    "label" : "My Bank",
    "icon"  : "https://mybank.com/icons/app.png",
    "supportedPaymentMethods", : [
        "https://visa.com/emvco_tokenized_debit/", 
        "https://w3.org/payments/methods/legacy_card/mastercard_credit/",
        "https://nacha.org/directdebit/", 
        "https://banksbucks.example.com/", 
    ],
    "appstoreId" : "87345656", //Platform specific extension for iOS
    "playstoreId" : "com.mybank.paymentapp", //Platform specific extension for Android
    "endpoint" : "https://mybank.com/app/v2",
});

Here are some notes on what this data is intended to mean:

  • The label and icon would be used by the payment mediator when prompting the user to select a payment app.
  • The id is private data used by the Payment App provider to identify the app (e.g., version information).
  • The strings identify Payment Methods (see Issue 34). In this example, the customer has multiple ways to pay represented by those strings: ** a VISA debit card. Visa has defined the EMV Tokenized Visa Debit payment method which has a mechanism whereby the app returns an EMVCo tokenization scheme compliant token instead of the clear PAN. This requires the app to either store this token of fetch it from a token server as required. To support this payment method the payment app must be capable of doing this and understand the format of the request and response messages it must process and return. ** a MasterCard credit card. The Legacy MasterCard payment method is a very simple protocol (that could be defined by the W3C) where the payment app simply returns the clear PAN, expiry and CVV2 to the merchant. ** direct debits from the bank account ** bank's proprietary loyalty points system (let's call this fictional program BankBucks).
  • On mobile some of the app meta data would be provided in the app manifest or whatever platform-specific mechanism is used to provide app meta-data (such as supported custom-URL protocols and intents etc) or not be required (such as for label and icon). note: The mobile os platform specific extensions might allow the API call in a mobile browser to trigger a prompt to the user to install the mobile app from the app store.

Through registration, Payment App data (in the form of a manifest) is provided to the Payment Mediator.

Payment Initiation

The user visits a merchant Web site, adds some items to a shopping cart, and proceeds to checkout. The merchant site calls the payment API passing a payment request object that lists accepted Payment Methods (identifiers not shown):

In this example, the merchant has chosen not to support the "Legacy MasterCard" payment method because they have chosen to not put their website in scope for PCI DSS so they don't support methods that send card data in the clear.

Notes on some scenarios:

  • If the user has no matching Payment Apps, the merchant could redirect the user to a payment page hosted by the merchant PSP where the user is able to use legacy payment methods, or simply offer the user a "traditional" payments page. Especially during a transition period when the protocol is being adopted across user agents, it will be important for merchants to provide a usable fallback experience.
  • @@Todo: Describe the process if the user has no payment apps installed
  • The merchant could offload this entire process to their PSP by allowing the PSP to call the payment API from an iframe. (@@Todo: Add an issue for the WG's attention: This implies we should allow calls to the payment API even if they are not from the top-level browsing context however this would need to be carefully controlled for security.)

Payment App Invocation

Based on the Payment Methods accepted by the merchant and the Pyment Methods supported by the user's registered Payment Apps, the Payment Mediator prompts the user to select one Payment App for the transaction. In this example, because the Payment Mediator is part of the user's desktop browser, the browser provides the UI to prompt the user to choose the Payment App. On a mobile device, for example, we might expect the mobile OS to follow the usual app selection patterns. Note that in this model the user selects a Payment App in this model, not a payment instrument/funding source/payment method.

Let's assume here the user selects the BankBucks app. The Payment Mediator invokes the app and sends it a version of the payment request that has been "trimmed" to include only the data relevant for the supported Payment Methods.

sidenote: There could be a way that the merchant can influence the choice of payment method after a user has picked a payment app so this is not entirely under the control of the payment app. The risk is that payment app publishers will try to maximise the fees they earn at the expense of the merchant while the user is potentially ignorant of this even happening. At a minimum the merchant should be able to incentivize the user to use specific payment methods by surfacing price differences that may be available during app selection.

Payment App User Interaction

The Payment App helps the user select from among supported Payment Methods. In this example, the Payment App fetches the latest balance for all of the user's funding sources. The user doesn't have enough BankBucks points for this purchase but is given the option to split the payment: points for a portion and ACH direct debit or Visa for the rest. The user selects points plus the VISA Debit card.

Payment App Response

The Payment App calls the bank's tokenisation service for an EMVCo compliant token for the Visa cardm, then returns a response to the Web site with relevant information, such as which portion was paid with points, which portion with Visa, and the tokenized Visa Debit payment details. The merchant forwards the response to their PSP, who processes the two payments.

sidenote: The ability to split a payment between two payment methods will likely not be supported by the standard in "version 1" as this requires consideration of a number of complex failure scenarios. Rather it is expected that PSPs that wish to support this will wrap it in their own custom payment method (such as BankBucks in this case). The response will be a BankBucks format response but will have another payment method response embedded instructing the PSP to split the payment. The PSP, knowing how to interpret BankBucks responses will know how to extract the other payment method response and how to deal with the complex failure scenarios should one payment method fail.

Previous section: Architecture components

Next section: Deployment Examples.

Home

A Payments Initiation Architecture for the Web

Clone this wiki locally