Square payment form

Overview of 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, credit, Square gift cards, or digital wallet payment cards.

This section provides an overview of how to integrate Square payments in your website. At the end of the overview, we provide 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 setup 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 of the Square SDKs 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/debit cards

  • Square Gift cards

  • Digital wallets - Google Pay, Apple Pay, and MasterPass

Payment source support varies by country. read Supported Payment Methods by Country for more information.

For credit/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. We recommend that you create separate instances of the SqPaymentFrom library, one for each payment source you want 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 towards the end of the topic.

Implementation summary
Permalink Get a link to this section

This section covers two things:

  • SqPaymentForm library overview

  • An overview of the implementation, how you integrate the library in your website

We recommend you review this section, and then try the Walkthrough: Integrate Square Payments In a Website.

SqPaymentForm library overview
Permalink Get a link to this section

The key components of this library are:

  • Functions - a set of useful functions. For example, requestCardNonce generates a single-use secure token (called nonce) using the payment source input the buyer provides. You then use 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, postalCode). You might also allow digital wallets (Google Pay, Apple Pay, or masterpass) as a payment source on your website by configuring related data fields (googlePay, applePay, masterpass). The following screenshot shows SqPaymentForm library rendering payment form that supports a card payment and 2 of the digital wallets:

paymentform-4fields--with-wallets

  • Callback functions - These functions run when specific events happen. Using these callbacks, you are able to 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 one or more 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 source information in the payment form, the library generates a single use, secure token called nonce. You then charge the nonce using 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. In summary, you do two things: integrate a payment form in your website and create a server-side component to charge the payment source.

Note

The code fragments are only for illustration and are not complete (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, you configure the SqPaymentForm library data fields ( configuration fields). For example, suppose you want to take only debit and credit card payments on your website. You might create a webpage as shown:

paymentform-4fields-paynowbutton

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

  1. Add reference to the SqPaymentForm library in your HTML section:

    <script type="text/javascript" src="https://js.squareupsandbox.com/v2/paymentform">
</script>

    The example shows sandbox domain in the URL. During development, you can use the environment for testing. When ready to deploy the website to production, you change the domain (js.squareup.com).

  1. In the HTML page, you 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 is an empty <div/> with an id. You 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, postalCode). The following example code fragment 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, we also provide custom implementation of the callback (cardNonceResponseReceived). For illustration, we show an alert statement.

  3. 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 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 of the Square SDK libraries to write server code to call the Square API Payments ( CreatePayment endpoint) and charge the nonce. For 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 (e.g., Apple Pay on the Web).

  • Apple Pay digital wallet support is only available for US Square merchant accounts

  • SqPaymentForm auto-populates fields (except CVV field) if the buyer has enabled autofill in the browser settings and stored credit card details in the browser. Browsers do not permit auto-population 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. We recommend that you create separate instances of the SqPaymentFrom library, one for each payment source you want 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 towards the end of the topic.

    • Gift card payments - You can configure 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 (say credit/debit cards), you create two instances of SqPaymentForm library, one for gift cards and another for any other payment sources.

    • Digital wallet payments - We support configuring the library to take digital wallet payments by themselves with additional considerations related to using single-element and multi-element payment form explained in the next bullet.

    • Single-element and multi-element payment form considerations

      • Single-element payment form - This payment form configuration supports taking only credit/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/debit card payments and also 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.