Exception Handling

Applies to: Web Payments SDK

Learn about how to handle common Web Payments SDK exceptions.

Each of the Web Payments SDK methods may throw JavaScript errors for certain exceptional circumstances. While most errors should be used to assist in diagnosing problems with initial SDK setup, there are a few key errors that benefit from a deeper understanding. This topic helps you learn more about these errors.

The full list of Web Payments SDK errors can be found in the SDK reference documentation.

Cause:

The PaymentMethodUnsupportedError error is thrown whenever a specific payment method is unusable. The message property of this error describes the reason in more detail.

Common reasons the Web Payments SDK might throw this error include:

• Your application is not set up to support this payment method.

  Example: - Most payment methods require registering them for your application in the developer console.

• The payment method is not supported on the buyer's browser.

  Example: - Apple Pay is only supported on Safari browsers.

• The payment method is temporarily disabled or otherwise inaccessible.

  Example: - Due to a third-party vendor outage, Square disables the payment method that requires it.

This error is normally thrown when the individual payment method is initialized.

Solution:

• Any payment method that can safely be turned off should have logic to handle the PaymentMethodUnsupportedError error.

Example: -

try {
  googlePay = await payments.googlePay();
} catch (e) {
  if (e.name === 'PaymentMethodUnsupportedError') {
    // disable the Google Pay method
  } else {
    // general exception handling for other error types
  }
}

Cause:

The BrowserNotSupportedError is thrown when a buyer's browser cannot use the Web Payments SDK at all. This differs from PaymentMethodUnsupportedError, which indicates that specific payment methods aren't supported while the SDK itself remains functional. When BrowserNotSupportedError occurs, the buyer must switch to a different browser to complete their transaction.

This error is normally thrown when the payments() method is called.

Solution:

This browser does not support the Web Payments SDK product. Any error messaging should direct the end-user to use another browser.

Example: -

try {
  payments = await square.payments();
} catch (e) {
  if (e.name === 'BrowserNotSupportedError') {
    // provide error message directing the end-user to use another browser
  } else {
    // general exception handling
  }
}

Cause:

The Web Payments SDK must be run from a fully secure HTTPS context. This is a standard security measure to protect end-users from MITM (man-in-the-middle) attackers.

Solution:

In order for a context to be considered secure, it must:

• be hosted using HTTPS/TLS
• use non-deprecated network security settings
• if contained within another page, that page must also be HTTPS/TLS

You can test your context using the JavaScript expression window.isSecureContext.