Payment Form: How it Works
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.
On This Page
Requirements and limitations
- Sites must use the Square-hosted version of the
- Square's payment form must be generated on a webpage that uses HTTPS. Debit, credit, and Masterpass payments may be
localhostwithout 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
SqPaymentForm library object includes these primary elements:
SqPaymentFormfunctions 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.
SqPaymentFormConfiguration fields —
SqPaymentFormdata fields that define HTML placeholder names, enable/disable payment features, and control presentation of the form fields.
SqPaymentFormCallback functions —
SqPaymentFormfunctions 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
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
SqPaymentForm library. Payment form field placement and style are defined by a web developer using CSS classes and
Payment form card input fields include:
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
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:
- A customer opens the page, which loads the
SqPaymentFormchecks to see if the browser is compatible. If not, the unsupportedBrowserDetected callback is invoked, which ends the process.
- The methodsSupported callback is invoked, which lists digital wallets are enabled and supported.
SqPaymentFormreplaces the HTML placeholders with iframes and the paymentFormLoaded callback is invoked.
- 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.
- The cardNonceResponseReceived callback is invoked.
- 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
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.
- Initialize the
SqPaymentFormwith Configuration fields , setting the
- Verify host browser support by calling isSupportedBrowser
- Build payment form by calling build
- Respond to the methodsSupported callback by updating the page user interface to show electronic wallet buttons for supported payment methods.
- 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
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
SqPaymentFormreceives 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.