Payment Method Identifiers

The Payment Request API [[!PAYMENT-REQUEST-API]] requires that merchants supply a list of identifiers for supported payment methods. This specification defines those identifier strings and how they are created.

The working group maintains a list of all bug reports that the group has not yet addressed. This draft highlights some of the pending issues that are still to be discussed in the working group. No decision has been taken on the outcome of these issues including whether they are valid. Pull requests with proposed specification text for outstanding issues are strongly encouraged.

This specification was derived from a report published previously by the Web Platform Incubator Community Group.

Introduction

To use Payment Request API, merchants (or their service providers) must know how to handle payment method specific data for those methods they claim to accept. This allows the API to abstract away the details of specific payment methods and to add new ones over time without changing the API specification.

As part of using Payment Request API, the Web page provides an array of strings that identify accepted payment methods. This specification defines those strings.

URLs as Payment Method Identifiers

When the party responsible for a payment method wishes to publish machine-readable information associated with the payment method, it does so with a URL. This URL approach offers at least two benefits: identifier decentralization and origins as a trust mechanism. In particular, owners of proprietary payment methods can use Web servers under their control to publish security information about authorized payment apps.

The Web Payments Working Group is developing a payment method manifest specification for the information a payment method owner would want to publish. Payment method identifiers that are URLs will help user agents locate these manifest files using a mechanism defined in that specification. Payment Manifest Proposal.

Either in the payment method manifest specification or in separate "good practice" documentation, the Working Group should address issues of server performance for payment method identifiers that are URLs. Furthermore, when parties feel they do not need to publish a manifest, we should explain that a manifest with an explicit machine-readable assertion that "any payment app may implement" is preferable to lack of a manifest.

Syntax

When URLs are used for payment method identifiers they MUST be absolute URLs including, at most, a scheme, host, port and path. The URL must be a potentially trustworthy URL as defined in the [[SECURE-CONTEXTS]] specification. Identifier URLs MUST have null query and fragment values.

Matching

User agents MUST use the following algorithm to determine whether two payment method identifiers that are URLs match:

Let A be the first payment method identifier string and let B be the second payment method identifier string.
Let urlA be the result from the URL parser when parsing A with no base URL.
If either urlA.query or urlA.fragment are not null terminate the algorithm with a result of no match and discard A from further matching.
Let urlB be the result from the URL parser when parsing B with no base URL.
If either urlB.query or urlB.fragment are not null terminate the algorithm with a result of no match and discard B from further matching.
The identifiers match if urlA equals urlB using the URL equivalence test (i.e. the test returns true).

W3C-Defined Strings as Payment Method Identifiers

W3C expects to publish a small number of payment method specifications that define abstractions across similar payment methods (such as credit card payments, tokenized payments, or credit transfers). W3C expects these payment methods will be implemented in a wide variety of third party payment apps. W3C identifies these payment methods with (short) strings; W3C expects to mint these strings in payment method specifications published by the Web Payments Working Group.

Syntax

The syntax of W3C strings used as payment method identifiers is constrained by this regular expression:

          [a-z0-9-]+

Matching

For W3C strings, user agents MUST use exact string matching.

Conditional Matching Beyond Payment Method Identifier Matching

For some payment methods, merchants may wish to express that they accept a payment method but only under certain conditions (e.g., "I only credit cards from brand A and debit cards from brand B"). The Web Payments Working Group has discussed several ways to support more sophisticated matching beyond initial payment method identifier matching.

Parties may mint payment method identifiers to represent different conditions. This scalable approach may work well for a small number of independent conditions, but may not scale well for complex relationships.
A payment method can define "filters" that enable callers of the API to describe in finer detail the conditions under which they accept that payment method. User agents and third party payment apps can similarly scope their support for that payment method with these filters. In this scenario, a match between payee and payer depends first on matching payment method identifiers, then on filter alignment. Please note that at this time the Working Group's expectations is that filters will be defined within payment methods; there will not be "generic" filters that work across payment methods.

Introduction

Dependencies

URLs as Payment Method Identifiers

Syntax

Matching

W3C-Defined Strings as Payment Method Identifiers

Syntax

Matching

Conditional Matching Beyond Payment Method Identifier Matching