Square payment form

Square Payments in your Website

For integrating Square payments in your website, Square provides a secure, PCI-compliant, customizable payment experience for accepting payments. You can accept payments from sources such as debit cards, credit cards, Square Gift Cards, or digital wallet payment cards.

This section provides an overview of how to integrate Square payments in your website and provides a walkthrough with step-by-step instructions to set up an example website with Square payments integrated.

Libraries you use
Permalink Get a link to this section

You use the following Square-provided libraries to set up a website with Square integrated for payment processing:

  • SqPaymentForm library. This is the client-side JavaScript library you use to develop a payment form in your web page. The payment form provides an encrypted nonce representing a payment card accepted by the form.

  • Square APIs (Payments API). You add a server-side component to your website to charge the nonce. You can use any Square SDK for this. These are wrapper libraries that underneath make the REST API calls to the Square Payments API.

Supported payment sources
Permalink Get a link to this section

You can configure the SqPaymentForm library in your website to take payments from the following payment sources:

  • Credit and debit cards

  • Square Gift Cards

  • Digital wallets, including Google Pay and Apple Pay

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

payment-form-two-configs

On your website, you can allow payments from a combination of the preceding payment sources. You should create separate instances of the SqPaymentFrom library, one for each payment source you want to support. However, if you want to initialize only one SqPaymentForm instance to support multiple payment sources, there are some considerations. These are discussed in the Requirements and limitations section later in this topic.

Implementation
Permalink Get a link to this section

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 Walkthrough: Integrate Square payments in a website.

SqPaymentForm library
Permalink Get a link to this section

The key components of this library are:

  • sqPaymentForm functions. You can use requestCardNonce, for example, to generate a single-use secure token (called a nonce) using the payment source input that the buyer provides. You can then use a server-side component to charge the payment source using the nonce.

  • Configuration fields. The payment form that the library renders depends on the data fields you configure. For example, to take credit card payments, you configure related fields (cardNumber, cvv, expirationDate, and postalCode). You might also allow digital wallets (Google Pay or Apple Pay) as a payment source on your website by configuring related data fields (googlePay and applePay). The following shows the SqPaymentForm library rendering a payment form that supports a card payment and two of the digital wallets:

paymentform-4fields--with-wallets

  • Callback functions. These functions run when specific events happen. Using these callbacks, you can integrate your business logic with the payment process. For example, after the requestCardNonce library function returns, the cardNonceResponseReceived callback provides the results. If execution is successful, the library provides a nonce; otherwise, it provides a list of errors. You can provide custom implementation of this callback to process the results the way you want (for example, to send the nonce to your backend for taking the payment).

  • paymentRequest objects and paymentDetailsUpdate objects. The library provides these objects for use when working with digital wallets.

After a buyer provides payment card information in the payment form, the library generates a nonce. You then charge the card using a server-side component.

Implementation summary
Permalink Get a link to this section

The section provides a high-level summary of integrating Square payments in your website. You can integrate a payment form in your website and create a server-side component to charge the payment source.

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
Permalink Get a link to this section

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:

paymentform-4fields-paynowbutton

Build this payment form with DOM elements and map each element to a SqPaymentForm data field as follows:

  1. 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, you can use the environment for testing. When you are ready to deploy the website to production, you set the domain to js.squareup.com.

  1. In the HTML page, add elements for each of the card input fields. For example:

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

    • In each credit 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, you call the SqPaymentForm library function (requestCardNonce) to generate a nonce.

  2. Initialize an instance of the SqPaymentForm object 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:

    <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, custom implementation of the callback (cardNonceResponseReceived) is provided. For illustration, an alert statement is shown.

  1. Provide implementation of the button click event handler. In this code, you call the requestCardNonce library function to generate a nonce.

         function onGetCardNonce(event) {
       paymentForm.requestCardNonce();
     }

These are the core payment form components. You can take card information as input and have the SqPaymentForm library generate a nonce. In the next step, you develop a server-side component to charge the payment source represented by the nonce.

Create a server-side component
Permalink Get a link to this section

You can use any Square SDK library to write server code to call the Square API Payments CreatePayment endpoint and charge the nonce. For more information, see Take Payments. The example walkthrough provides the code.

Requirements and limitations
Permalink Get a link to this section

  • 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 autopopulates 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 autopopulation of the CVV field for security reasons.

    Note

    The payment form cannot accept payment cards and Square Gift Cards together. To add both payment types to 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 SqPaymentFrom 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.

Walkthrough
Permalink Get a link to this section

For a complete working example, with step-by-step instructions, see Walkthrough: Integrate Square Payments in a Website.