Learn about the Square Web Payments SDK for taking payments in a web client.
Web Payments SDK

Web Payments SDK Overview

The Square Web Payments SDK is a JavaScript browser-client SDK that provides a secure payment-card entry method, along with other secure payment methods. The SDK is the client part of the client/server Square payment solution. The SDK produces a secure one-time-use payment token that your application web client sends to your backend, where it is processed as a payment with the Payments API. To view an example of such an application, see Take a Card Payment with the Web Payments SDK.

Did you know?

If you intend to migrate your application from the deprecated SqPaymentForm library to the Web Payments SDK, read Migrate to the Web Payments SDK to get the specifics about replacing the SqPaymentForm integration in your application with the Web Payments SDK.

Payment methods Permalink Get a link to this section

The following payment methods are available to your application to accept payment with the Web Payments SDK:

Card Payments

Accept card payments and collect card data

Digital wallets: Apple Pay and Google Pay

Accept digital wallet payments from Apple Pay or Google Pay

ACH Bank Transfer

Accept ACH bank transfer payments

Gift Cards

Accept gift card payments

Afterpay

Accept Afterpay payments

Cash App Pay

Accept Cash App Pay payments


The Web Payments SDK can be integrated with your payment page in as few as 10 lines of code to provide one of the available payment methods.

Web Payments SDK features Permalink Get a link to this section

The Web Payments SDK was created to make integration with your web application simpler and provide better performance. The SDK provides the following advantages:

  • Granular configuration. You only need to write configuration code for the payment methods that your application accepts. Each payment method has its own objects with configuration options appropriate for the method.

  • Promise-based pattern. The async/await pattern is used in place of the callback pattern of earlier payment libraries. This pattern lets your application react to events in a more reasonable way with less code.

  • Automatic localization. The SDK determines the locale of the buyer's browser automatically. However, your application can override localization by setting a configuration option.

Payment tokens Permalink Get a link to this section

The Web Payments SDK produces payment tokens from any of the following payment methods:

  • Credit and debit payment cards

  • Google Pay

  • Apple Pay

  • Gift card

  • ACH bank transfer using Plaid for bank account authentication

  • Afterpay

  • Cash App Pay

The payment tokens produced by these payment methods share a common format and are all accepted by the Payments API as source_id values. The server-side Payments API code that you write for one of these tokens works seamlessly for all the other methods. You can write unique client logic for each payment method, but you only need one payment process flow on the server.

You can also get a payment token for use with the Cards API if you need to store a card on file with a customer. This is useful when your application must support recurring card-not-present payments.

Customers Permalink Get a link to this section

The Web Payments SDK does not create a new customer in the Square account where a payment is credited. If you want to create a new customer along with a payment on a Square account, you need to collect at least one of the following pieces of information about a buyer:

  • Given name

  • Family name

  • Company name

  • Buyer email address

  • Buyer phone number

The backend of your application can take this information and create a customer profile using the Customers API. When your backend creates a Payment object using the Payments API CreatePayment endpoint, it includes the Web Payments SDK-provided payment token and the new customer ID.

Card acceptance with postal codes Permalink Get a link to this section

The Web Payments SDK shows a postal code input field on the payment form after the SDK determines the country that issued the buyer's credit. The Web Payments SDK displays the proper form label for the postal code based on the country:

  • For US, the form displays "ZIP".

  • For CA, the form displays "Postal Code".

  • For UK, the form displays "Postcode".

If the payment form displays the postal code field, then the payment requires a postal code for the buyer to proceed. The Web Payments SDK enforces input field validation for the postal code depending on the country.

Payment session timeout Permalink Get a link to this section

The payment session times out after 24 hours. If the buyer has not completed filling out the payment form, the buyer must refresh the browser to complete the payment. Fields that generate based on the issuing country of the credit card may not save input that the buyer entered.

Requirements and limitations Permalink Get a link to this section

  • The Web Payments SDK cannot be used with Internet Explorer 11.

  • The Web Payments SDK does not create payments or customers.

  • In the EU, payments that do not provide authentication get a CARD_DECLINED_VERIFICATION_REQUIRED error for transactions that require authentication. This error means that the seller did not implement verifyBuyer on the customer-initiated payments. For more information, see VerifyBuyerError.

Next steps Permalink Get a link to this section

The following topic shows how to add card payment logic to an example application:

Note

If you have already implemented the Payments API in your application, you can replace the localhost domain and URL used in the Web Payments SDK example code and samples with your own server endpoint URL.

Related topics Permalink Get a link to this section

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.