Native-app Payment Handler

2. Native-app payment handlers

A native-app payment handler is a payment handler, as defined in [payment-request], that is backed by some underlying native payment app that can be accessed via a native payment app provider. Native payment apps are deliberately loosely defined, simply as some form of application that is not a web-based application as defined in [web-based-payment-handler]. This allows for user agent flexibility to provide access to, for example, applications that use web technologies but which are external to the user agent.

2.1. Verifying native-app payment handler claims

Native payment apps have both an authoritative payment method identifier (defining the root of authority for their cryptographic identity) and a set of claimed payment method identifiers, which the app claims it is capable of handling. Verification of these claims relies upon the payment and application manifests specified in [payment-method-manifest] and [appmanifest].

NOTE: See § 1.2 Payment app trust model for an overview of the first-party and third-party verification trust models.

Should we allow for alternate methods to verify the claims, to support cases like payment apps built into the browser? [Issue #2]

Given a payment method identifier, identifier, and a native payment app, app, the following steps determine if app is allowed to handle the payment method identifier identifier:

1. If identifier is not a URL-based payment method identifier, return false.

2. Let claimedIdentifiers be the claimed payment method identifiers for app.

3. If claimedIdentifiers does not contain identifier, return false.

4. Let authoritativeIdentifier be the authoritative payment method identifier for app.

5. Let origin be authoritativeIdentifier’s origin.

6. If origin is not allowed for identifier, return false.

7. Let authoritativePaymentMethodManifest be the ingested and parsed payment method manifest for authoritativeIdentifier. If ingestion or parsing fails, return false.

8. For each URL webAppManifestURL in authoritativePaymentMethodManifest’s default applications:

   1. Let webAppManifestString be the result of fetching the web app manifest at webAppManifestURL. If the fetch fails, continue to the next iteration of this loop.

   2. Let webAppManifest be the result of running the steps for processing a web app manifest given webAppManifestString and manifest URL webAppManifestURL. If processing fails, continue to the next iteration of this loop.

   The payment method manifest spec should cache and attach the relevant web-app manifests to the payment method manifest, so we don’t have to do this. [Issue #8]

   1. If app is a related application for webAppManifest, return true.

9. Return false.

2.1.1. Determining if an origin is allowed for a payment method identifier

This algorithm should probably exist in [payment-method-manifest] rather than here. [Issue #3]

To determine if an origin, origin, is allowed for a payment method identifier identifier, run the following steps:

1. Let paymentMethodManifest be the ingested and parsed payment method manifest for identifier. If ingesting or parsing fails, return false.

2. If origin is equal to identifier’s origin, return true.

3. If paymentMethodManifest’s supported origins is the string '*', return true.

4. If paymentMethodManifest’s supported origins contains origin, return true.

   NOTE: The supported origins can either be the string "*", indicating that any origin is allowed to handle this identifier, or an explicit set of allowed origins.

5. Return false.

NOTE: A URL-based payment method identifier retains its string identity and origin as originally specified by the website or payment app, regardless of any same-site HTTP redirects encountered during discovery or retrieval of its payment method manifest. Manifest discovery redirects locate the manifest resource, but do not mutate the payment method identifier.

2.2. Integration with [payment-request]

As with all payment handlers, websites utilize a PaymentRequest object to interact with native-app payment handlers. This section describes the steps the user agent MUST take when mediating between a PaymentRequest object and one or more native payment apps from a single native payment app provider.

2.2.1. Can make payment algorithm

When performing step 8.2. of the can make payment algorithm from [payment-request] for a payment method identifier identifier, which determines if the user agent has a payment handler that supports handling payment requests for identifier, the user agent MUST perform the following steps:

1. For each available native payment app provider provider:

   1. Get the list of native payment apps known to provider. Let the result be paymentApps.

   2. For each paymentApp in paymentApps:

      1. If paymentApp is allowed to handle the payment method identifier identifier, resolve hasHandlerPromise with true and terminate any remaining steps.

2.2.2. The show() method

When performing step 17.5. of the PaymentRequest.show() method for a PaymentRequest, which constructs the list of registered payment handlers for a payment method identifier identifier, the user agent MUST perform the following steps:

1. For each available native payment app provider provider:

   1. Get the list of native payment apps known to provider. Let the result be paymentApps.

   2. For each paymentApp in paymentApps:

      1. If paymentApp is allowed to handle the payment method identifier identifier, create a native-app payment handler for paymentApp and append it to the list of registered payment handlers.

When a native-app payment handler is selected by the user (steps 19-24 of the show() algorithm), the user agent MUST invoke the native payment app corresponding to the selected native-app payment handler, passing the transaction details and any requested PaymentOptions.

The [payment-request] spec is quite vague about what data is or should be passed to an invoked payment handler. We should be more specific. [Issue #1]

NOTE: The invoked payment app will ultimately communicate a result back to the user agent, either by indicating success, indicating user cancellation, or indicating internal error.

2.2.3. Steps to check if a payment can be made

The steps to check if a payment can be made for a native-app payment handler and JSON-serialized PaymentMethodData.data object are:

1. Return true.

NOTE: No steps are necessary here. We have already verified the payment handler’s claims in § 2.2.2 The show() method and made sure that they match the identifier. No additional filtering is needed based on the serialized data.

2.2.4. Steps to respond to a payment request

The steps to respond to a payment request for a PaymentRequest, request, and a native-app payment handler, handler, are:

1. Let app be the underlying native payment app for handler.

2. Let result be the result of retrieving the converted result details for app. If result is failure, return failure.

3. If result.methodName is not one of the payment method identifiers supported by request, or if app is not allowed to handle the payment method identifier result.methodName, return failure.

4. Set request.[[response]].methodName to result.methodName.

5. If the user agent delegates shipping address collection to app:

   1. Let address be the result of running the create a ContactAddress from user-provided input algorithm, treating result.shippingAddress as the user-provided input.

   2. Set request.[[response]].shippingAddress to address.

   3. Set request.[[response]].shippingOption to result.shippingOption.

6. If the user agent delegates payer name collection to app:

   1. Set request.[[response]].payerName to result.payerName.

7. If the user agent delegates payer email collection to app:

   1. Set request.[[response]].payerEmail to result.payerEmail.

8. If the user agent delegates payer phone collection to app:

   1. Set request.[[response]].payerPhone to result.payerPhone.

9. Return result.details.

[payment-request] needs to be updated to allow payment handlers to populate the full PaymentResponse (e.g., delegated shipping and payer data), rather than only the details. [Issue #5]

2.2.5. Payment method changed algorithm

When a native payment app, app, informs the user agent that the user has changed their payment method with a payment method identifier methodName and method-specific details, methodDetails (an object or null), the user agent MUST run the following steps:

1. Let request be the active PaymentRequest for app.

2. If methodName is not one of the payment method identifiers supported by request, or if app is not allowed to handle the payment method identifier methodName:

   1. Notify payment details not updated in app.

   2. Terminate these steps.

3. Run the payment method changed algorithm from [payment-request] on request with methodName and methodDetails. Let event be the dispatched PaymentMethodChangeEvent.

4. Propagate payment detail updates for event and app.

NOTE: An invoked native payment app can support multiple payment methods (such as its default payment method identifier and third-party payment method identifiers authorized by manifests). The native payment app explicitly supplies methodName so the user agent knows which payment method the user switched to.

2.2.6. Shipping option changed algorithm

When a native payment app, app, informs the user agent that the user has changed their shipping option to a DOMString, shippingOption, the user agent MUST run the following steps:

1. Let request be the active PaymentRequest for app.

2. Run the shipping option changed algorithm from [payment-request] on request, with shippingOption as the user-provided input. Let event be the dispatched PaymentRequestUpdateEvent.

3. Propagate payment detail updates for event and app.

2.2.7. Shipping address changed algorithm

When a native payment app, app, informs the user agent that the user has changed their shipping address to a ContactAddress, shippingAddress, the user agent MUST run the following steps:

1. Let request be the active PaymentRequest for app.

2. Run the shipping address changed algorithm from [payment-request] on request with shippingAddress. Let event be the dispatched PaymentRequestUpdateEvent.

   Currently the shipping address changed algorithm in [payment-request] does not actually allow for an input parameter, instead using non-specific user-provided input. This should be updated to explicitly take a parameter (which may require changing [contact-picker] as well). [Issue #6]

3. Propagate payment detail updates for event and app.

2.2.8. Propagating payment detail updates

When a PaymentRequestUpdateEvent or PaymentMethodChangeEvent event, event, is dispatched on a PaymentRequest request for an invoked native payment app app, the user agent MUST run the following steps to propagate payment detail updates to app:

1. If updateWith(detailsPromise) was invoked on event:

   1. In parallel, wait for detailsPromise to settle.

   2. If detailsPromise resolves with a PaymentDetailsUpdate details:

      1. Let update be the result of running convert a PaymentDetailsUpdate to a PaymentRequestDetailsUpdate with details and app.

         NOTE: We convert from a PaymentDetailsUpdate to a PaymentRequestDetailsUpdate to remove information that the payment app does not need to know, such as the displayItems.

      2. Update payment details in app with update.

   3. Else (if detailsPromise rejects):

      1. Notify payment details not updated in app.

2. Otherwise:

   1. Notify payment details not updated in app.

[payment-request] assumes the user agent renders the payment UI itself, and needs to provide extension hooks for payment handlers to receive the resolved PaymentDetailsUpdate from updateWith(). [Issue #7]

2.3. Delegating user information collection

When a website creates a PaymentRequest with PaymentOptions that request data about the user, the user agent can either collect this information itself or it can delegate the collection of this information to the selected native-app payment handler.

enum PaymentDelegation {
  "shippingAddress",
  "payerName",
  "payerPhone",
  "payerEmail"
};

Given a PaymentRequest, request, and a native payment app, app:

1. The user agent delegates shipping address collection to app if request.[[options]].requestShipping is true and app’s supported delegations contains "shippingAddress".

2. The user agent delegates payer name collection to app if request.[[options]].requestPayerName is true and app’s supported delegations contains "payerName".

3. The user agent delegates payer email collection to app if request.[[options]].requestPayerEmail is true and app’s supported delegations contains "payerEmail".

4. The user agent delegates payer phone collection to app if request.[[options]].requestPayerPhone is true and app’s supported delegations contains "payerPhone".

Delegation should really be a concept defined in [payment-request] and then implemented by this specification, not both defined and implemented here. This would then allow [web-based-payment-handler] to also rely on the central [payment-request] definition. [Issue #8]

2.4. The NativePaymentHandlerResponse dictionary

A native payment app provides its transaction response to the user agent using the NativePaymentHandlerResponse dictionary.

dictionary NativePaymentHandlerResponse {
  DOMString methodName;
  object details;
  DOMString? payerName = null;
  DOMString? payerEmail = null;
  DOMString? payerPhone = null;
  ContactAddress? shippingAddress = null;
  DOMString? shippingOption = null;
};

methodName

The payment method identifier for the payment method used to complete the transaction.

details

An object containing payment method specific information supplied by the native payment app to complete the transaction.

payerName

The payer’s name, if payer name collection was delegated to the native payment app.

payerEmail

The payer’s email address, if payer email collection was delegated to the native payment app.

payerPhone

The payer’s phone number, if payer phone collection was delegated to the native payment app.

shippingAddress

The shipping address selected by the user, if shipping address collection was delegated to the native payment app.

shippingOption

The id of the shipping option selected by the user, if shipping address collection was delegated to the native payment app.

2.5. The PaymentRequestDetailsUpdate dictionary

When a native payment app communicates an update to the transaction (such as a change of payment method, shipping option, or shipping address), the user agent provides the website’s updated transaction details back to the native payment app using a PaymentRequestDetailsUpdate dictionary as defined in [web-based-payment-handler].

2.5.1. Converting a PaymentDetailsUpdate to a PaymentRequestDetailsUpdate

Given a PaymentDetailsUpdate, details, and a native payment app, app, the following steps convert a PaymentDetailsUpdate to a PaymentRequestDetailsUpdate:

1. Let update be a new PaymentRequestDetailsUpdate dictionary.

2. If details["error"] exists, set update.error to details["error"].

3. If details["total"] exists, set update.total to details["total"].amount.

   NOTE: This step strips out the label from the information shared to the app, as it does not need to know that.

4. If the user agent delegates shipping address collection to app:

   1. If details["shippingAddressErrors"] exists, set update.shippingAddressErrors to details["shippingAddressErrors"].

   2. If details["shippingOptions"] exists, set update.shippingOptions to details["shippingOptions"].

5. If details["paymentMethodErrors"] exists, set update.paymentMethodErrors to details["paymentMethodErrors"].

6. If details["modifiers"] exists:

   1. Let matchingModifiers be a new empty list.

   2. For each modifier in details["modifiers"]:

      1. If app is allowed to handle the payment method identifier modifier.supportedMethods, append modifier to matchingModifiers.

   3. Set update.modifiers to matchingModifiers.

7. Return update.

3. Native payment app provider model

The native-app payment handler API relies on an abstract functional model through which the user agent can interact with native payment apps. This section describes that model.

The native payment app provider model is an abstract functional model which describes the behavior of some native payment app provider (e.g., the operating system) that facilitates access to underlying native payment apps.

Providers MAY implement and expose this abstract model in any way desired, as long as the normative requirements of the model are met. See § 5 Example implementations of the native payment app provider model.

3.1. Returning a list of native payment apps

A native payment app provider MUST provide a method the user agent can call to get the list of native payment apps known to the provider. This method returns a list of native payment apps.

3.2. Authoritative payment method identifier

Given a native payment app, app, a native payment app provider MUST provide a method the user agent can call to get the authoritative payment method identifier for app. This method returns a URL-based payment method identifier whose payment method manifest serves as the root of authority for app’s identity (that is, a payment method manifest whose default applications include at least one web app manifest that has app as a related application).

The user agent MUST verify that the claim is valid (see § 2.1 Verifying native-app payment handler claims).

3.3. Claiming payment method identifiers

Given a native payment app, app, a native payment app provider MUST provide a method the user agent can call to get the claimed payment method identifiers for app. This method returns a set of URL-based payment method identifiers that app claims it is capable of handling. This set MUST include app’s authoritative payment method identifier.

The user agent MUST verify that the claim is valid for each identifier (see § 2.1 Verifying native-app payment handler claims).

3.4. Supporting delegations

Given a native payment app, app, a native payment app provider MUST provide a method the user agent can call to get the supported delegations for app. This method returns a set of PaymentDelegation values that app supports.

3.5. Checking if a native payment app is a related application for a web app manifest

A native payment app provider MUST provide a method the user agent can call to determine if a native payment app is a related application for a web app manifest. The native payment app provider MAY utilize the information contained in the related applications member of the manifest, such as the id, platform, or fingerprints of each specified external application resource.

3.6. Determining if a native payment app can handle a PaymentRequest

A native payment app provider MUST provide a method the user agent can call to determine if a native payment app is able to handle a payment request for a given PaymentRequest request. In order to support this functionality, the user agent MAY pass information about request to the native payment app, subject to the following requirements:

1. If the user agent is operating in a private browsing mode, the user agent MUST NOT pass information to or query the native payment app. The user agent MAY decide that an app is able to handle a payment request based on whether the app is installed and verified.

See § 4.1 Tracking risks from readiness checks for considerations here.

NOTE: This functionality is used to answer the hasEnrolledInstrument method on PaymentRequest, which was removed from the [payment-request] specification but is still shipping in multiple browser engines.

3.7. Invoking a native payment app

A native payment app provider MUST provide a method the user agent can call to invoke the native payment app for a given native payment app, including converting the input data (see § 2.2.2 The show() method) to a form that the native payment app understands.

When run, this method MUST pass control of the current experience over to the invoked native payment app, until the native payment app indicates success, indicates user cancellation, or indicates internal error. Depending on the capabilities of the native payment app provider, the invoked app MAY be displayed partially over the user agent window (to improve user context and understanding of the flow).

3.8. Changing the payment method

A native payment app provider MUST provide a method by which an invoked native payment app, app, can inform the user agent that the user has changed their payment method. When this method is called, the native payment app provider MUST perform the following steps:

1. Let methodName be the payment method identifier provided by the native payment app.

2. Let methodDetails be the method details provided by the native app, converted into an object, or null if no details are provided.

3. Run the payment method changed algorithm, passing in app, methodName, and methodDetails.

3.9. Changing the shipping option

A native payment app provider MUST provide a method by which an invoked native payment app, app, can inform the user agent that the user has changed their shipping option. When this method is called, the native payment app provider MUST run the following steps:

1. Let shippingOption be the result of converting the native-app specific data representing the id into a DOMString.

   NOTE: As the website code will ultimately match shippingOption to the id for one of the options they originally provided, care must be taken to preserve identity when converting this value to and from native-app specific data.

2. Run the shipping option changed algorithm, passing in app and shippingOption.

3.10. Changing the shipping address

A native payment app provider MUST provide a method by which an invoked native payment app, app, can inform the user agent that the user has changed their shipping address. When this method is called, the native payment app provider MUST run the following steps:

1. Let shippingAddress be the result of running the create a ContactAddress from user-provided input algorithm, using the data provided by the native-app as the user-provided input.

2. Run the shipping address changed algorithm, passing in app and shippingAddress.

3.11. Updating payment details in an invoked native payment app

A native payment app provider MUST provide a method the user agent can call to update payment details in an invoked native payment app, given a PaymentRequestDetailsUpdate dictionary, update. When called, the provider MUST transmit update to the invoked app, converting the dictionary fields into a native format.

3.12. Notifying payment details not updated in an invoked native payment app

A native payment app provider MUST provide a method the user agent can call to notify payment details not updated in an invoked native payment app. When called, the provider MUST inform the invoked app that the website made no changes to the transaction details in response to the change event.

3.13. Indicating success of an invoked native payment app

A native payment app provider MUST provide a way for an invoked native payment app to indicate success back to the user agent. When this occurs, the user agent MUST run the user accepts the payment request algorithm from [payment-request].

A native payment app provider MUST provide a way for the user agent to retrieve the converted result details for an invoked native payment app that has indicated success. This method returns a NativePaymentHandlerResponse dictionary containing the transaction result (converting native-app specific response data into the appropriate dictionary fields), or failure if the response data is missing or invalid.

3.14. Indicating user cancel from an invoked native payment app

A native payment app provider MUST provide a way for an invoked native payment app to indicate user cancellation back to the user agent. When this occurs, the user agent MUST run the user aborts the payment request algorithm from [payment-request].

3.15. Indicating internal error from an invoked native payment app

A native payment app provider MUST provide a way for an invoked native payment app to indicate internal error back to the user agent. When this occurs, the user agent MUST run the payment handler indicates an internal error algorithm from [payment-request].