Provides additional ways to customize the behavior of the Square payment form processing page.
Square Payment Form

Customize Payment Form Behavior Deprecated
This component is deprecated. See below for guidance about what to use instead.


The Square payment form is deprecated and replaced by the Web Payments SDK.

You should use the Web Payments SDK to take payments on a web client. The Web Payments SDK uses modern web styling as shown in the following image:

A graphic showing the five visual elements of the Card payment method, which are represented as selectors that you specify in a card option styling object.

Overview Permalink Get a link to this section

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

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 payment token.

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 Permalink Get a link to this section

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:

Customize the onLoad behavior Permalink Get a link to this section

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:

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.


    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 Permalink Get a link to this section

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 you need more assistance, contact Developer Support or ask for help in the Developer Forums.