Improved error codes

[dtjones404]

Hi team,

We wanted to see if there’s any interest in reviving the functionality described in issue #871. For context, our PayPal SDK exposes onError and onCancel callbacks, which allow merchants to respond differentially to checkout failures caused by uncaught errors during the processing of a transaction, and those caused by the buyer intentionally abandoning the transaction (e.g. by closing the payment window.) Currently, this requires us to distinguish between AbortErrors based on error.message:

#handlePaymentError(
    error,
  ) {
    if (
      [
        "Request cancelled", // used by Chrome <= 76, Opera 63
        "User closed the Payment Request UI.", // Chrome 77+, Edge 79+, Opera 64+
      ].includes(
        error.message,
      )
    ) {
      this.paymentFlowOptions.onCancel?.();
    } else {
      this.paymentFlowOptions.onError?.(error);
    }
  }


This works but we’d prefer to have a solution that isn’t dependent on vendor-specific error messages which might change in the future.

[stephenmcgruer]

cc @rsolomakhin

[rsolomakhin]

I would be in favor of using OperationError for checkout failures caused by uncaught errors and AbortError for the buyer intentionally abandoning the transaction.

@marcoscaceres - Would you be on-board for this change?

[rsolomakhin]

@dtjones404 - A couple of questions for you:

1. Consider websites that check only for the error codes currently defined in the spec: AbortError, SecurityError, RangeError, InvalidStateError, NotSupportedError, and NotAllowedError. What will happen when a new error code is returned? Is there a way to make this transition smoother?
2. Consider different release cycles and cadences for different browsers: What if Safari ships the new error code a few months before Chrome or vice versa?
3. Consider supporting older browser versions* during the transition period - some newer browsers will have the new error code, while some older one's won't.
4. Consider how browsers gradually roll out features. For example, Chrome may enable new error codes for 1% of users to observe metrics. Then user agent version check would not work.

Some thoughts off the cuff:

1. Feature detection: Add a static method PaymentRequest.isErrorCodeSupported(errorCode)?
2. Feature control: Introduce enableOperationErrorCode: true boolean parameter to the new PaymentRequest() constructor?

• • Speaking of older browser versions, (this is totally unrelated to the topic at hand, so -- my apologies!) your code example mentions Chrome <= 76, which released quite a while ago. Older browser versions tend to have known vulnerabilities that are patched up in the newer versions. Do you consider this an increased risk for payments? How long do you support old versions?

[dtjones404]

Hi @rsolomakhin, thanks for the suggestions!

Using feature detection with an opt in control seems like a good idea and would certainly work for our use case. Most likely our strategy in that case would be to use the improved errors if available, and if not fall back to our existing implementation. That way, we would have better future-proofing, since we wouldn’t be relying on string matching moving forward, but we’d still be compatible with browsers that haven’t implemented the new error code.

Differentiating between the two error classes also seems like the right choice moving forward, and we’d hope to see it become the default behavior in the future, but getting there without breaking existing integrations is tricky.

Our overall strategy for the PayPal JS SDK is to support a minimum of Chrome 69, but we have the ability to facilitate payment through other flows (e.g. opening a popup) if PaymentRequest isn’t recommended in older browsers. Exposing something like a PaymentRequest spec version could potentially help us with that, and with feature detection in general, although I’m not sure how feasible that is. We aren’t always able to determine browser version reliably with user agent checks, since some of our merchants consider it to be PII.

[rsolomakhin]

Hi @dtjones404 - Web APIs generally prefer feature detection over version checks. For example, if Chrome rolls out a feature to 50% of its population for an A/B test, then the version check would not be useful.

@marcoscaceres - Do you foresee any issues here before we proceed with a pull request to the spec? We can always discuss this further in the pull request as well.

[rsolomakhin]

Hi @dtjones404, the error handling code would be similar to the following. Is that something that you would consider safe to add to your code-base even today, given that it's hidden behind feature detection?

const paymentRequest = new PaymentRequest(
        supportedMethods, paymentDetails, {enableOperationErrorCode: true});
// ...
#handlePaymentError(
    error,
  ) {
    if (!PaymentRequest. isErrorCodeSupported || !PaymentRequest.isErrorCodeSupported("OperationError")) {
      // Check error message.
      if (
        [
          "Request cancelled", // used by Chrome <= 76, Opera 63
          "User closed the Payment Request UI.", // Chrome 77+, Edge 79+, Opera 64+
        ].includes(
          error.message,
        )
      ) {
        this.paymentFlowOptions.onCancel?.();
      } else {
        this.paymentFlowOptions.onError?.(error);
      }
    } else {
        // Check error code.
        if (error.name === "OperationError") {
          this.paymentFlowOptions.onError?.(error);
        } else {
          this.paymentFlowOptions.onCancel?.();
        }
    }
  }


[dtjones404]

Hi @rsolomakhin, yes that approach should be safe for us 👍 .

[rsolomakhin]

@dtjones404 - Would you like to run an experiment where you add this sample code to your SDK/Demo and then Chrome Canary adds the feature behind a flag, so we can iterate together and make sure that the design is correct before we commit it to the W3C spec?

(We would do this with the understanding that this is an experiment.)

This process will give you an opportunity to influence changes directly in the browser. The W3C spec and Chrome launch process would be a formality (instead of a blocker) afterwards.

[dtjones404]

Sounds great @rsolomakhin! We've implemented the changes and we're planning to get them deployed to our sandbox environment as soon as possible, but it may have to wait until after the holidays.

[rsolomakhin]

Good to hear, @dtjones404! Would it be possible for us to access the sandbox environment, as we develop the feature in Chrome, or is that something that's restricted to only your organization? It would be good to have something publicly visible to send to blink-dev@chromium.org in an "Intent to Prototype" email.

[dtjones404]

Hi @rsolomakhin! Yes, our sandbox environment is publicly accessible. We have a test integration available at https://codepen.io/gregjopa/pen/xbKXqwJ which might be useful. You'll need to create sandbox credentials at https://developer.paypal.com/home/ if you want to login to the PayPal app and complete the checkout process, but that shouldn't be necessary for testing whether onCancel is invoked, since that only requires closing the payment window. I've also attached a recording of the process for reference.

pp-phdemo.mov

[rsolomakhin]

Hi @dtjones404 , would you be interested in talking about this enhancement at the next Web Payments Working Group, in order to gauge wider support for this proposal?

[dtjones404]

Hi @rsolomakhin , sorry for the delay. Yes, I would be happy to attend the next Web Payments Working Group and discuss the need for this new error code for the "cancel" use case."