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.

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, and postalCode) 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 the SqPaymentForm 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, the cardNonceResponseReceived 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.

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:

  Copy

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

  Copy

     <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 an id. Use the ID in the next step to map these elements to corresponding SqPaymentForm library configuration fields.

  • The button specifies the onclick event handler (onGetCardNonce). In this handler code, call the SqPaymentForm.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 the SqPaymentForm configuration fields (cardNumber, cvv, expirationDate, and postalCode). The following code fragment example shows the initialization:

  Copy

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

  Copy

       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 the CVV field) if the buyer has enabled autofill in the browser settings and stored credit card details in the browser. Browsers do not permit automatic population of the CVV 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 one SqPaymentForm 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.