Take Payments

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 Transactions API to collect eCommerce payments.

Requirements and limitations

  • Sites must use the Square-hosted version of the SqPaymentForm library. Applications referencing a copy of the JavaScript library hosted on a non-Square server will be disabled without notice.
  • Square's payment form must be generated on a webpage that uses HTTPS. Debit, credit, and Masterpass payments may be tested with localhost without using HTTPS, but HTTPS is required for all Apple Pay transactions.
  • Apple Pay on the Web requires domain registration with Apple. payment form will not render the Apple Pay button unless Apple indicates the site domain is valid.
  • Nonces 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 (e.g., Apple Pay on the Web).
  • Square's API sandbox does not support Apple Pay on the Web at this time.

The SqPaymentForm object

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.
  • Digital wallet 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).

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

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.

Diagram sqpaymentform labeled
Payment form components

Payment form card input fields include:

  • cardNumber
  • cvv
  • expirationDate
  • postalCode

A web app 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.

The SqPaymentForm process flow

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. The customer clicks on a digital wallet button or clicks "Pay with card".
    • If a digital wallet is clicked, the createPaymentRequest callback is invoked. The validateShippingContact callback is also invoked if the digital wallet supports address selection and the user selects or changes a shipping address in the digital wallet UI.
    • If "Pay with card" is clicked, JavaScript on the page calls the SqPaymentForm.requestCardNonce() function.
  6. The cardNonceResponseReceived callback is invoked.
  7. 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 7 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

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 initally 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

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 transaction 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 occured on the nonce request, the callback provides actionable details. This callback provides the nonce that a payment page posts to the web app backend where the Transaction API is used to create a payment.
Prev
< Payment Form Setup Guide

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow