Customize Payment Form Behavior

This topic explores some of the advanced features of the payment form library.

Overview

To integrate a payment form in your website, use the SqPaymentForm JavaScript library as shown in Walkthrough: Integrate Square Payments in a Website. The library provides a set of configuration fields, functions, data types, and callback functions. In the walkthrough, you initialize a SqPaymentForm instance by setting some of the configuration fields (such as cardNumber, cvv, postal code, and expirationDate), provide implementation for a callback (cardNonceResponseReceived), and call the library functions (such as requestCardNonce) to generate a nonce.

This topic also explores other SqPaymentForm features to customize the payment form. You should complete the walkthrough exercise so that you can test these SqPaymentForm customizations.

Remove the postal code requirement

For processing credit cards for a seller in the United States (US), Canada (CA), and the United Kingdom (GB), the postal code (postalCode) is a required payment field. For sellers taking payments in Japan, you can remove the postal code requirement by setting the postalCode configuration field to false in the SqPaymentForm initialization as shown:

// Create and initialize a payment form object
const paymentForm = new SqPaymentForm({

...
  postalCode: false,

  // SqPaymentForm callback functions
  callbacks: {
      ...
  }
});

Customize the onLoad behavior

After the SqPaymentForm loads, the paymentFormLoaded callback runs your custom code. You can use this callback to take actions, such as:

• Using the setPostalCode function to set the postal code value for the convenience of the buyer, using information previously entered (for example, from a billing address).

• Using the focus function to set the input focus on a particular SqPaymentForm input field.

For example, this code fills the postal code with the buyer's billing address code and then sets the input focus on the payment card number field:

callbacks: {

    ...
    paymentFormLoaded: function() {
      paymentForm.setPostalCode("POSTAL CODE FROM BILLING");
      paymentForm.focus("cardNumber");
    }
  }
});

Note the following:

• You can only call the setPostalCode function inside the paymentFormLoaded callback.

• A successful call to the setPostalCode function generates the postalCodeChanged event causing the inputEvenReceived callback to execute.

  Note

  To preserve PCI compliance and ensure that credit card information is collected securely, you cannot programmatically fill the card number, CVV, or expiration date.

Detect unsupported browsers

The SqPaymentForm library provides the isSupportedBrowser function to detect unsupported host browsers before you instantiate the SqPaymentForm library. When a host browser is not supported, the callback runs your custom logic to tell the buyer that the payment form cannot be loaded in the unsupported browser.

if (SqPaymentForm.isSupportedBrowser()) {
  var paymentForm = new SqPaymentForm({ ... });
} else {
  // Tell buyer that their browser is not supported
}