From daca03c34bcca1e881005fde617c8f361c70b097 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Wed, 30 Mar 2016 15:56:49 -0400 Subject: [PATCH] Add option 1b to payment method identifier spec. --- specs/method-identifiers.html | 136 +++++++++++++++++++++++++++++++++- 1 file changed, 132 insertions(+), 4 deletions(-) diff --git a/specs/method-identifiers.html b/specs/method-identifiers.html index ba6e256b..cb22596e 100644 --- a/specs/method-identifiers.html +++ b/specs/method-identifiers.html @@ -74,7 +74,7 @@ Web Platform Incubator Community Group.

- +

Introduction

@@ -102,13 +102,13 @@

Payment Method Identifier

The Payment Method Identifier is a string that uniquely identifies a payment method that a user can use to complete a transaction. For example, Visa, MasterCard, and American Express are payment methods used in some countries.

-
+
This document currently specifies multiple alternate options for payment method identifiers. The Working Group has - not yet selected an approach, which might be one documented in this specification or another as yet undocumented proposal.
+ not yet selected an approach, which might be one documented in this specification or another as yet undocumented proposal.
-

Option 1

+

Option 1a

This section describes an approach to payment method identifiers using URLs.

@@ -211,6 +211,134 @@

Discussion topics

+
+

Option 1b

+

+ This section describes a way of expressing payment method identifiers + using machine-readable URLs that may be aliased to + developer-friendly short identifiers. +

+ +
+

Identifier format

+

+ Payment method identifiers are + absolute URLs that may optionally be + aliased using short identifiers. For example, + https://visa.com/payment-methods/VisaDebit (URL) or + VisaDebit (short identifier). +

+
+ +
+

Short Identifier Registry

+

+ A mapping file establishing short identifiers to payment method + identifier URLs can be found at + https://w3.org/registries/web-payments/v1. + To reduce the load on fetching this file, it is encouraged that + applications hard code the mappings. +

+

+ Any short identifier registry that is not re-parsed every time + will require a message version identifier to be embedded in the + messages that use the short identifiers. The assumption here is + that there is some versioning mechanism that is used by payment + messages such that the payment apps and merchants know how to + process short identifiers. +

+

+ The format of the document located at the short identifier registry + URL above still needs to be determined. Options include a plain + JSON document or a JSON-LD document. The mappings would be as simple + as: "VisaDebit": "https://visa.com/payment-methods/VisaDebit". +

+

+ It is assumed that once the short identifier registry file is created, + it is never updated. The Working Group may periodically release + v2, v3, etc. registry files. +

+
+ +
+

Content at Payment Method Identifier URLs

+

+ Payment method identifier URLs that resolve to content: +

+
    +
  1. MUST be served over HTTPS,
    2. +
  2. SHOULD support HTTP Content Negotiation,
    3. +
  3. SHOULD provide a human-readable document that describes the + payment method when text/html is requested, and
    4. +
  4. SHOULD provide a machine-readable document that describes the + payment method when application/ld+json is requested. +
    5. +
+
+ +
+

Identifier Equivalence

+

When the PaymentRequest API is invoked, the web page provides a + list of identifiers for supported payment methods. The user agent + must compare these identifiers to those available to the user and + use this to filter what the user can select. To determine whether + two identifiers match, perform the following test:

+
    +
  • Let A be the first payment method identifier and + let B be the second payment method identifier.
    • +
  • If A or B is listed in the Short Identifier + Registry, replace the value with its corresponding + absolute URL.
    • +
  • Let urlA be the result from the URL parser + when parsing A.
    • +
  • Let urlB be the result from the URL parser when + parsing B.
    • +
  • The identifiers match if urlA equals + urlB using the URL equivalence test + (i.e. the test returns true).
    • +
+
+
+

Dependencies

+

This section relies on several other underlying specifications.

+
+
URL
+
The terms URL, absolute URL, URL parser, and URL equivalence are defined by [[!url-1-20141209]] (or the editor's draft).
+
+
+
+

Discussion topics

+

The following observations are made about this option:

+
    +
  • + This option satisfies all requirements that Option 1 satisfies. +
    • +
  • + Advantages over Option 1a: +
      +
    • Relative URL and Base URL processing is avoided entirely + while ensuring that short identifiers can be used.
      • +
    • The Web Payments Working Group only has to maintain a + short identifier mapping file, not a complete payment method + identifier registry.
      • +
    • Hard coding and/or aggressive caching of the short identifier + mappings are encouraged as changes to the short identifiers + are disallowed after every major release.
      • +
    • Machine-readable information is encouraged to be published at + payment method identifier URLs but is not required.
      • +
    +
    • +
  • + Disadvantages wrt. Option 1a: +
      +
    • + None +
      • +
    +
+
+
+

Option 2

This section describes an approach to payment method identifiers using strings that might be reverse domain names.