Square Payments in your Website
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 nonce (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.
On this page
Resources used for application development
Use the following Square-provided resources to set up a website with Square integrated for payment processing:
SqPaymentForm library. This client-side JavaScript library creates an encrypted single-use payment token by accepting buyer input into the payment form that it renders on your web page. The library does not charge the payment method. That is done on your server-side component.
Square Payments API. Add a server-side component to your website to charge the nonce. You can use any Square SDK for this. These libraries emit REST API calls to the Square Payments API.
Supported payment methods
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 GiftCards, which require a separate instance of the library.
Implementation
This section covers:
An overview of the
SqPaymentForm
library.An overview of the implementation and how you integrate the library in your website.
After you review this section, try the Walkthrough: Integrate Square Payments in a Website.
SqPaymentForm library
The key components of this library are:
sqPaymentForm functions. Use
requestCardNonce
, to generate a single-use secure token (called a nonce) using the payment method input that the buyer provides. You can then use a server-side component to charge the payment method using the nonce.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 (
cardNumber
,cvv
,expirationDate
, andpostalCode
) 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 theSqPaymentForm
library. 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
requestCardNonce
function, thecardNonceResponseReceived
callback provides the results. If your nonce request succeeds, the callback provides a nonce; otherwise, it provides relevant errors. Use this callback to get the nonce and send it to your backend for taking the payment with the Payments API.paymentRequest and paymentDetailsUpdate types. The library provides these types for use when taking digital wallet payments.
After a buyer provides payment card information in the payment form, the library generates a nonce. You then charge the card using your Payments API enabled server component.
Implementation summary
This section provides a high-level summary of integrating Square payments in your website.
Note
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.
Develop a payment form in your 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
SqPaymentForm
library in your HTML<head/>
section:<script type="text/javascript" src="https://js.squareupsandbox.com/v2/paymentform"> </script>
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
js.squareup.com
.
In your HTML page, add elements for each of the card input fields.
<div id="form-container"> <div id="sq-card-number"></div> <div id="sq-expiration-date"></div> <div id="sq-cvv"></div> <div id="sq-postal-code"></div> <button id="sq-creditcard" onclick="onGetCardNonce(event)">Pay $1.00</button> </div>
Note:
In each payment card field there is an empty
<div/>
with anid
. Use the ID in the next step to map these elements to correspondingSqPaymentForm
library configuration fields.The
button
specifies theonclick
event handler (onGetCardNonce
). In this handler code, call theSqPaymentForm.requestCardNonce
function to request a nonce.
Initialize an instance of
SqPaymentForm
as shown in the following code fragment. In the initialization, map the form fields (using the IDs) to theSqPaymentForm
configuration fields (cardNumber
,cvv
,expirationDate
, andpostalCode
). The following code fragment example shows the initialization:<script type="text/javascript"> const paymentForm = new SqPaymentForm({ cardNumber: { elementId: 'sq-card-number', placeholder: 'Card Number' }, cvv: { elementId: 'sq-cvv', placeholder: 'CVV' }, expirationDate: { elementId: 'sq-expiration-date', placeholder: 'MM/YY' }, postalCode: { elementId: 'sq-postal-code', placeholder: 'Postal' }, // SqPaymentForm callback functions callbacks: { cardNonceResponseReceived: function (errors, nonce, cardData) { alert(`The generated nonce is:\n${nonce}`); } } }); </script>
In the preceding
SqPaymentForm
initialization, a default implementation of the callback (cardNonceResponseReceived
) is provided. In practice, use the callback to get the nonce and POST it to your backend for payment.
Provide implementation of the button
click
event handler. In this code, call the requestCardNonce function to request a nonce:function onGetCardNonce(event) { paymentForm.requestCardNonce(); }
These are the core payment form components. The payment form takes card fields as input and
SqPaymentForm
generates a nonce. In the next section, learn about developing a server-side component to charge the payment source represented by the nonce.
Create a server-side component
Use any Square SDK library to write server code to call the Square Payments API CreatePayment endpoint and charge the nonce. For more information, see Take Payments.
Requirements and limitations
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 (such as Apple Pay).
Apple Pay digital wallet support is only available for US Square seller accounts.
SqPaymentForm
automatically populates fields (except theCVV
field) if the buyer has enabledautofill
in the browser settings and stored credit card details in the browser. Browsers do not permit automatic population of theCVV
field for security reasons.Note
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
SqPaymentForm
library, one for each payment source that you want to support. However, if you want to initialize only oneSqPaymentForm
instance to support multiple payment sources, there are some considerations:Gift Card payments. You can configure a
SqPaymentForm
library 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
SqPaymentForm
library: 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
SqPaymentForm
instance.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
SqPaymentForm
library instance.