The Web Payments SDK is a JavaScript browser-client SDK that provides a secure payment-card entry method, along with other secure payment methods.
The following video introduces the Web Payments SDK and demonstrates how to get started. For an optimal viewing experience, expand the video window to a desired size or watch the video on YouTube. For a detailed overview, see the following sections.
The Web Payments SDK enables the client implementation of the client/server Square online payment solution. The SDK produces a secure single-use payment token that your application web client sends to your backend, where it's processed as a payment with the Payments API. For more information, see Take Payments.
The backend is the server part of the client/server Square payment solution, which processes the payment using a payment token. Square provides the Payments API as a backend solution for application developers to process payments.
Link to section
Requirements and limitations
The Web Payments SDK cannot be used with Internet Explorer 11.
The Web Payments SDK doesn't create payments or customers on its own. The SDK must be used alongside the Payments API and the Customers API.
Chrome extensions don't work with the Web Payments SDK.
In the EU, payments that don't provide authentication get a CARD_DECLINED_VERIFICATION_REQUIRED error for transactions that require authentication. This error means that the seller didn't implement verifyBuyer on the customer-initiated payments. For more information, see VerifyBuyerError.
Link to section
SDK and payment acceptance implementation
The overall implementation flow with the Web Payments SDK and a payment acceptance backend service works as follows:
Configure the Web Payments SDK client library with your application to render a payment method form and generate a payment token.
Configure the Payments API, or another backend service, to take the payment token and process the payment.
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. To set the locale with your application, use the setLocale() method and pass the locale for when the application creates a new Payment object instance. The Web Payments SDK supports the following languages:
English (Australia)
English (Canada)
English (Ireland)
English (United Kingdom)
English (United States)
French (Canada)
French (France)
Japanese
Spanish
Link to section
Payment tokens
The Web Payments SDK produces payment tokens from these supported payment methods: credit card, gift card, digital wallets, ACH bank transfer, Afterpay, and 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 to 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.
Link to section
Create a customer profile
The Web Payments SDK doesn't 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:
First 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 CreatePayment endpoint, it includes the Web Payments SDK-provided payment token and the new customer ID.
Link to section
Accepting cards with postal codes
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 card. 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, the payment requires a postal code for the buyer to proceed. The SDK enforces input field validation for the postal code depending on the country.
Important
The postal code field isn't supported for Japan and China. The field doesn't display on the payment form if a card is issued by a Japanese or a Chinese bank. If you're building your application in the Square Sandbox for sellers in these regions, you might still see the payment form render the postal code field if a Sandbox test card is used for testing purposes.
Link to section
Payment session timeout
The payment session times out after 24 hours. If the buyer hasn't completed 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 might not save input that the buyer entered.
Link to section
Enable Content Security Policy directives
If your application deploys a Content Security Policy (CSP) with the Web Payments SDK, you must enable the following CSP directives to add an additional security layer:
Square provides examples of application integrations where you can initialize the Web Payments SDK with a backend to process payments. The following examples are provided on GitHub.
If you've 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.