Square Payment Form
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. Web Payments SDK uses modern web styling as shown in the following image:
For integrating Square payments in your website, Square provides a secure, PCI-compliant, customizable payment experience for accepting payments. Your application can accept payments from sources such as debit cards, credit cards, Square gift cards, or digital wallet payment cards. For information about Square online payment processing fees, see Payments Pricing with Square APIs and SDKs.
To learn how to get a payment token with the payment form, see Walkthrough: Integrate Square Payments in a Website. The walkthrough gives step-by-step instructions with detailed explanations and example code.
Use the following Square-provided resources to set up a website with Square integrated for payment processing:
You can configure the
SqPaymentForm library in your website to take payments with the following buyer payment methods:
Credit and debit cards.
Square gift cards.
Digital wallets, including Google Pay, Apple Pay, and Secure Remote Commerce (SRC). SRC was previously known as Masterpass.
Payment method support varies by country. For more information, see Supported Payment Methods by Country.
For credit and debit cards, the library supports single-element and multi-element configurations as shown:
On your website, you can allow payments from a combination of the preceding payment methods. You can use one instance of the
SqPaymentForm for all of the payment methods except for Square gift cards, which require a separate instance of the library.
This section covers:
An overview of the
An overview of the implementation and how you integrate the library in your website.
After you review this section, try Walkthrough: Integrate Square Payments in a Website.
The key components of this library are:
sqPaymentForm functions. Use
requestCardNonceto generate a single-use secure token using the payment method input that the buyer provides. You can then use a server-side component to charge the payment method using the payment token.
Configuration fields. The style of the payment form and the payment methods accepted are determined by what values you set in the configuration fields. For example, to take credit card payments, set the (
postalCode) fields with DOM placeholder values. Accept digital wallets (Google Pay, Apple Pay, or SRC) by setting other data fields. The following image is the payment form rendered by the
SqPaymentFormlibrary. The example accepts a card payment and two of the digital wallets:
Callback functions. These functions are invoked by specific events. Use these callbacks to integrate your business logic with the payment form. For example, after your logic calls the
cardNonceResponseReceivedcallback provides the results. If your payment token request succeeds, the callback provides a payment token; otherwise, it provides relevant errors. Use this callback to get the payment token and send it to your backend for taking the payment with the Payments API.
After a buyer provides payment card information in the payment form, the library generates a payment token. You then charge the card using your Payments API enabled server component.
This section provides a high-level summary of integrating Square payments in your website.
The code fragments are incomplete and illustrate the use of the library. The example walkthrough provides step-by-step instructions for you to set up an example website.
Depending on the payment sources you want to support, configure the
SqPaymentForm library configuration fields. For example, suppose you want to take only debit and credit card payments on your website. You might create a web page as shown:
Build this payment form with DOM elements and map each element to a
SqPaymentForm data field with the following tasks:
Add a reference to the
SqPaymentFormlibrary in your HTML
The example shows the Sandbox domain in the URL. During development, use the environment for testing. When you are ready to deploy the website to production, set the domain to
In your HTML page, add elements for each card input field.
In each payment card field there is an empty
id. Use the ID in the next step to map these elements to corresponding
SqPaymentFormlibrary configuration fields.
onclickevent handler (
onGetCardNonce). In this handler code, call the
SqPaymentForm.requestCardNoncefunction to request a payment token.
Initialize an instance of
SqPaymentFormas shown in the following code fragment. In the initialization, map the form fields (using the IDs) to the
SqPaymentFormconfiguration fields (
postalCode). The following code fragment example shows the initialization:
In the preceding
SqPaymentForminitialization, a default implementation of the callback (
cardNonceResponseReceived) is provided. In practice, use the callback to get the payment token and POST it to your backend for payment.
Provide implementation of the button
clickevent handler. In this code, call the requestCardNonce function to request a payment token.
These are the core payment form components. The payment form takes card fields as input and
SqPaymentFormgenerates a payment token. In the next section, learn about developing a server-side component to charge the payment source represented by the payment token.
SqPaymentFormlibrary can only be hosted in a Square server (squareup.com or squareupsandbox.com). An application that loads the library from any other domain is disabled without notification.
Payment tokens created with digital wallets cannot be used to store a customer card on file.
Shipping address validation is only available for digital wallets that support address selection in their UI (such as Apple Pay).
Apple Pay digital wallet support is only available for US Square seller accounts.
SqPaymentFormautomatically populates fields (except the
CVVfield) if the buyer has enabled
autofillin the browser settings and stored credit card details in the browser. Browsers do not permit automatic population of the
CVVfield for security reasons.
An instance of the payment form cannot accept both payment cards and Square gift cards. To support both payment types on a payment page, you must create two instances of
SqPaymentForm: one instance for payment cards and another instance for Square gift cards.
On your website, you can allow payments from a combination of the preceding payment sources. You should create separate instances of the
SqPaymentFormlibrary, one for each payment source that you want to support. However, if you want to initialize only one
SqPaymentForminstance to support multiple payment sources, there are some considerations:
Gift card payments. You can configure a
SqPaymentFormlibrary instance to take only gift cards. You cannot combine the same instance to configure other payment sources.
To allow gift cards and any other payment sources (such as credit and debit cards), you create two instances of the
SqPaymentFormlibrary: one for gift cards and another for any other payment sources.
Digital wallet payments. Square supports configuring the library to take digital wallet payments by themselves with additional considerations related to using a single-element and a multi-element payment form.
Single-element and multi-element payment form considerations:
Single-element payment form. This payment form configuration supports taking only credit and debit card payments. To allow another source, such as a digital wallet, you must initialize another
Multi-element payment form. When you choose the multi-element payment form configuration, you can take credit and debit card payments, as well as digital wallet payments using a single