Square Payment Form

How It Works

Learn how to customize the payment form using the programming model and call flow of the SqPaymentForm JavaScript library.

Customize the payment experience of the Square payment form by using a Square JavaScript library (SqPaymentForm). The library looks for HTML placeholders and replaces them with iframes to create a secure payment form. The payment form accepts debit or credit card, Apple Pay on the Web, Google Pay, and Masterpass payment details then generates an encrypted payment token, known as a nonce. Nonces are used with Square's Payments API to collect eCommerce payments.


Digital wallet functionality (Apple Pay on the Web, Masterpass) in the Square payment form is only supported for accounts based in the United States.

SqPaymentForm object Permalink Get a link to this section

The SqPaymentForm library object includes these primary elements:

  • SqPaymentForm FunctionsSqPaymentForm functions that let you control the lifecycle of the form. Single-page web applications can use these functions to build the payment form at any place in a host page lifecycle.

  • SqPaymentForm Configuration fieldsSqPaymentForm data fields that define HTML placeholder names, enable/disable payment features, and control presentation of the form fields.

  • SqPaymentForm Callback functionsSqPaymentForm functions triggered when specific events happen. The behavior of these functions is fully customizable.

  • SqPaymentForm paymentRequest objects — Data objects used specifically for digital wallet payments and formatted in accordance with the requirements of various wallet services (e.g., Apple Pay on the Web).

  • SqPaymentForm paymentDetailsUpdate objects — Data objects used specifically for Apple Pay payments to update payment amounts when shipping options or shipping contact is changed in the Apple Pay sheet.

The SqPaymentForm Technical Reference provides full details and examples of using SqPaymentForm objects to integrate the payment form in a web app.

Payment form basic user interface Permalink Get a link to this section

The basic payment form with the optional digital wallet renders in a web page as shown in the following image. The example page labels and headers are provided by application HTML and the payment form components are built by the SqPaymentForm library. Payment form field placement and style are defined by a web developer using CSS classes and HTML page structure.


Payment form components

Payment form card input fields include:

  • cardNumber

  • cvv

  • expirationDate

  • postalCode

A web application assigns these fields to HTML placeholder elements during SqPaymentform initialization. digital wallet supported buttons can be hidden or shown by custom logic in a callback function run by the SqPaymentForm library.

SqPaymentForm process flow Permalink Get a link to this section

Payment form looks for placeholder HTML elements to generate a secure payment form that supports payments from debit or credit cards, Apple Pay on the Web, and Masterpass. In general, the steps for rendering a payment form with optional electronic wallet buttons, and requesting a nonce are:

  1. A customer opens the page, which loads the SqPaymentForm library.

  2. SqPaymentForm checks to see if the browser is compatible. If not, the unsupportedBrowserDetected callback is invoked, which ends the process.

  3. The methodsSupported callback is invoked, which lists digital wallets are enabled and supported.

  4. SqPaymentForm replaces the HTML placeholders with iframes and the paymentFormLoaded callback is invoked.

  5. Optional: The customer clicks on a digital wallet button.

    1. The createPaymentRequest callback is invoked.

    2. For Apple Pay:

  6. Optional: The customer clicks "Pay with card". JavaScript on the page calls the SqPaymentForm.requestCardNonce() function.

  7. The cardNonceResponseReceived callback is invoked.

  8. JavaScript on the page handles the nonce response:

    • If nonce generation succeeds, set the hidden nonce field and submit the form.

    • If nonce generation fails, handle the errors and provide feedback to the customer.

The cardNonceResponseReceived callback can return any of these seven nonce generation errors:

  • VALIDATION_ERROR - The provided data is invalid.

  • INVALID_APPLICATION_ID - The application ID provided when initializing the payment form is invalid.

  • MISSING_APPLICATION_ID - An application ID was not provided when initializing the payment form.

  • MISSING_CARD_DATA - One or more card data fields was not filled out in the payment form.

  • TOO_MANY_REQUESTS - Your application has generated nonce generation requests to frequently. Try again later.

  • UNAUTHORIZED - Your application is not authorized to use the Connect API to accept online payments.

  • UNKNOWN - An unknown error occurred.

SqPaymentForm process flow diagram:

The following diagram shows the payment form process flow. Components with dash line borders are asynchronous callbacks invoked by the SqPaymentForm library in response to state changes initiated by user actions. process-flow

Single-page web applications: Customizing SqPaymentForm lifecycle Permalink Get a link to this section

If your application is a single-page web application, you may want to delay initializing and building the payment form until the hosting page DOM is loaded and in a specific state. The following steps assume that the page was initially loaded and then placeholder tags were added to the DOM at some point later.

  1. Initialize the SqPaymentForm with Configuration fields , setting the autoBuild configuration to false.

  2. Verify host browser support by calling isSupportedBrowser

  3. Build payment form by calling build

  4. Respond to the methodsSupported callback by updating the page user interface to show electronic wallet buttons for supported payment methods.

  5. When payment form has returned a card nonce and is no longer needed, call destroy to cancel all event listeners for payment form.

Required function customizations Permalink Get a link to this section

Function customization can include adding or changing a CSS class on a page element, enabling or disabling digital wallet buttons, correcting error conditions, getting the payment card nonce provided by payment form after the createPaymentRequest function is called or one of the digital wallet buttons is clicked.

It is a best practice to customize all of the SqPaymentForm functions. However, the following functions must be customized for SqPaymentForm to provide a valid nonce:

  • methodsSupported — Called by Square's JS library when the page renders to decide which, if any, digital wallet button should be rendered in the payment form. Required if a payment page hosts digital wallet buttons for electronic payment services.

  • createPaymentRequest — Passes payment information to the digital wallet provider to create a wallet nonce. Called when a digital wallet button in the payment form is clicked.

  • cardNonceResponseReceived — Called when SqPaymentForm receives the result of a nonce generation request. The result will be a valid debit or credit card, wallet nonce, or an error. If an error occurred on the nonce request, the callback provides actionable details. This callback provides the nonce that a payment page posts to the web application backend where the Payments API is used to create a payment.