How It Works
Customize the payment experience of the Square payment form by using a Square
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 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.
SqPaymentFormpaymentRequest 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).
SqPaymentFormpaymentDetailsUpdate 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.
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 card input fields include:
A web app assigns these fields to HTML placeholder elements during
initialization. digital wallet supported buttons can be hidden or
shown by custom logic in a callback function run by the
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.
Optional: The customer clicks on a digital wallet button.
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
library in response to state changes initiated by user actions.
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.
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.
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
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
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
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 Payments API is used to create a payment.