Integrate Square Payments in a Website
Deprecated
This component is deprecated. See below for guidance about what to use instead.
Note
The Square payment form is deprecated and replaced by the Web Payments SDK.
You should use the Web Payments SDK to take payments on a web client. Web Payments SDK uses modern web styling as shown in the following image:
This topic provides a walkthrough with step-by-step instructions to set up a simple website integrated with Square for payments. We keep the exercise simple and build a basic form that only takes a credit card on a web page.
On this page
Overview
The following example shows a basic form that only takes a credit card on a web page. Digital wallet examples are not shown.
Subsequent topics explain how to add digital wallets to your website. The SqPaymentForm
technical reference is available when you need more information about one of the payment form library types or functions.
Processing payments in a website using Square is a two-step process:
Generate a secure single-use payment token. Use the Square
SqPaymentForm
client-side library to accept credit card and digital wallet payment information and to generate a secure single-use payment token.Charge the payment source using the payment token. Use the Square Payments API to charge the payment source that the token represents.
Follow this process to set up a website and test the setup by taking a payment. The walkthrough also shows how to review the payment on the Seller Dashboard.
Before you begin, note the following:
The walkthrough uses a Node.js web server project template that Square provides. Node.js is used because it is easy to set up and test. After finishing this walkthrough, you can explore similar examples in other languages provided on GitHub. For more information, see connect-api-examples.
The walkthrough uses the Square Sandbox environment for testing. In the Sandbox, you do not charge real credit cards, but instead use a test card that Square provides for Sandbox testing. After taking a payment, you see how the payment appears in the Sandbox Seller Dashboard.
If you are new to the Square payment form, you should follow the step-by-step instructions. A complete sample is available on GitHub for download if you want to check your project code at the end of this walkthrough.
Get ready
To prepare for the walkthrough:
Install Node.js and npm (a Node.js package manager).
Get your application credentials from the Square Developer Dashboard.
Download the project template created for this exercise.
Install Node.js and npm
When you install Node.js, you also get npm. For instructions, see Node.js.
Get Sandbox application credentials
The walkthrough uses the Square Sandbox environment for testing. Therefore, you use your Sandbox credentials.
Get your Sandbox application credentials from the Square Developer Dashboard. Use the Square Sandbox for testing so that you do not charge your real credit card.
Open the Developer Dashboard.
Choose the application you want to use in the Sandbox. If you do not have an application, create one. The application provides the credentials you need.
In the left pane, choose Credentials.
Make a note of the following values: Sandbox Application ID and Sandbox Access Token.
On the Locations page, choose a location ID to use in the first step of integration.
Use a client application ID to obtain a payment token in step 1: 1.1.3 and on the server side, the personal access token to create a payment using the Payments API in step 2.
Download the project template
For this exercise, start with a predefined project template to set up your initial web server.
Download or clone the Node.js project template:
Download the zip file and unzip the content to a local directory.
Clone the GitHub repository to a local directory.
Note
Cloned and downloaded projects create different directory names:
Cloned. Sqpaymentform-nodejs-starterkit
Downloaded. Sqpaymentform-nodejs-starterkit-master
Downloaded the full sample. Sqpaymentform-nodejs-starterkit-sample
Open a command line.
Change to the project directory.
Review the directory. Update the code in the following files in the project directory:
index.html is an empty static HTML page where you embed
SqPaymentForm
.mysqpaymentform.css is a sample CSS file (stylesheet) to customize the look of the card entry fields on the page.
server.js contains the server-side component that charges the payment source (step 2).
Run the following commands:
a. Install dependencies:
b. Start the server:
Open a browser and enter http://localhost:3000 to verify that the node server is running. You should see the following:
Now you are ready to build a web page that embeds SqPaymentForm
.
1.1: Embed SqPaymentForm in a static web page
Add the following components to the index.html page:
Required CSS and JavaScript references.
A
<div/>
with credit card fields.A
<script/>
, which manages theSqPaymentForm
object and user interaction using a JavaScript initializing block and<div/>
tags in the form.
1.1.1: Add script references
Open index.html and add the following references in the <head/>
section.
Note the following about these references:
js.squareupsandbox.com/v2/paymentform
is the Square JavaScript library used in testing the payment form in the Sandbox.mysqpaymentform.css
is the file provided as part of the project you downloaded.
Important
The SqPaymentForm
library can only be hosted in a Square server (squareup.com or squareupsandbox.com). An application that loads the library from any other domain is disabled without notification.
1.1.2: Add an HTML div
Add the following HTML <div/>
in the <body/>
section of the same index.html.
In the form, note the following:
Each credit card field is an empty
<div/>
with an ID.SqPaymentForm
replaces each<div/>
with an input element that runs securely on the Square domain. This allows the form to take credit card input while keeping your code outside of PCI scope.The
onclick
event handler (onGetCardNonce
) calls theSqPaymentForm.requestCardNonce
library function to get a payment token.
1.1.3: Add JavaScript to index.html
In this section, add code to the HTML page to configure and initialize the SqPaymentForm
object. <script/>
is added in the <body/>
because SqPaymentForm
can only be initialized after the DOM is fully loaded.
Copy and paste the following code into index.html after <!-- TODO: Add script from step 1.1.3 -->
:
In the JavaScript code, the callback cardNonceResponseReceived
alerts the user that a payment token is generated and returned by the SqPaymentForm
object. In step 2.1, the payment token is POSTed to a server-side component to charge the payment source. The server-side component is reviewed in step 2.
1.1.4: Add JavaScript to handle "Pay $1.00" button click event “onclick”
In this section, add a callback function to handle the pay button click event. The event handler calls requestCardNonce
to get the payment card token from the SqPaymentForm
object.
Copy and paste the following code into index.html after //TODO: paste code from step 1.1.4
:
1.1.5: Add JavaScript to build the form
In this section, add JavaScript to force the SqPaymentForm
object to render the payment form on the page.
Copy and paste the following code after //TODO: paste code from step 1.1.5
:
1.3: Test the payment form and verify the secure token
Complete the following steps to test the payment form:
Save all files.
Start the npm server, if it is not running:
Open a browser, and then open the payment form on localhost by entering http://localhost:3000 in the address bar.
Fill the form with the following Sandbox test credit card from the test values set, and then choose Pay $1.00.
Card Number: 4111 1111 1111 1111
MM/YY: 12/21 (you can provide any month and year in the future)
CVV: 111
Postal: 11111 (you can provide any postal code)
This is one of the test cards that Square provides for use in the Sandbox environment.
Verify that you get a payment token as shown in the following example:
Application flow summary
In this section, you do not perform actions. The section explains how the code you developed in step 1 works. You can read or skip ahead to step 2 to charge the payment source.
When the page loads, it renders the payment form defined in index.html. The page also downloads and executes the SqPaymentForm
JavaScript library. This is a library that provides the SqPaymentForm
object. For more information about the library, see SqPaymentForm object model.
The embedded JavaScript code does the following:
Initializes the
SqPaymentForm
with configuration fields and callback functions.Each credit card input form field requires a corresponding configuration field. For example, the
SqPaymentForm
initialization defines the card number input as shown in this inputTarget field.It maps the
SqPaymentForm.cardNumber
configuration field to corresponding form fieldsq-card-number
. TheSqPaymentForm
initialization also includes callback implementations; for example, theSqPaymentForm.cardNonceResponseReceived
. The callback executes afterSqPaymentForm
completes a request for a payment token.Provides code for the event handler
onGetCardNonce
that executes when you choose Pay $1.00.
After the payment form is built, it replaces DOM elements with iframes. The iframes take the buyer-entered credit card information and call the requestCardNonce
function to get a payment token. This allows you to take payments through Square.
When a buyer enters information in the form and chooses Pay $1.00, the onGetCardNonce
event handler executes. This code generates a payment token by calling the SqPaymentForm.requestCardNonce
function and passes the payment token back to the client by calling the SqPaymentForm.cardNonceResponseReceived
callback. The client displays an alert box with the generated payment token.
Step 2: Charge the payment source using the payment token
The index.html file sends the payment token to server.js by using the fetch API. Server.js uses it to create a payment. This server-side component uses the Square Node.js SDK library to call the Square Payments API to charge the payment source using the payment token. In step 2, you add the fetch code to index.html and update server.js with your access token.
2.1: Add JavaScript to send the payment token to the backend
In this section, you make a final change to index.html. Replace the alert that notifies on the payment token received with code that actually sends the payment token to server.js.
In index.html, replace
//TODO: paste code from step 2.1.1
with the following code that generates an idempotency key when the payment form page is loaded. This client-generated key prevents the same payment from being created multiple times.In index.html, replace
//TODO: paste code from step 2.1.2
with the following code that generates an idempotency key in the UUID format.Note
The
uuidv4
helper function generates a UUID, which should be less than 45 characters in length. The return value of the function is POSTed to the backend along with the payment token and is used as the idempotency key of theCreatePayment
request. As long as the UUID is not regenerated, the payment form cannot send a duplicate payment processing request.In index.html, find
//TODO: Replace alert with code in step 2.1
in the code you added in step 1.1.3, and replace the alert with the following code.Replace
REPLACE_WITH_LOCATION_ID
with a location ID from the Developer Dashboard for your application.
2.2: Configure the backend with your access token
The JavaScript code in server.js is already complete, but it is not set with your Sandbox access token. In this step, replace the placeholder with your token.
Open server.js.
Update the file by providing your Sandbox access token.
Review the following code fragments:
Create a
PaymentsApi
object and call theCreatePayment
endpoint to charge the payment source.Note that the
requestBody
specifies the payment token value and the amount to charge.
2.3: Test the payment flow from client to server
This time you generate a payment token and charge the payment source using the generated payment token.
Open a browser and enter http://localhost:3000.
Provide the card information:
Card Number: 4111 1111 1111 1111
MM/YY: 12/21 (you can provide any month and year in the future)
CVV: 111
Postal: 11111 (you can provide any postal code)
Choose Pay $1.00. After receiving the
Payments.CreatePayment
endpoint request, Square processes the payment and returns a response. A sample response fragment is shown:
Review the payment in the Sandbox Seller Dashboard. The payment is credited to the Sandbox test account whose access token is used in the application that you just built. To see the payment in the Sandbox Seller Dashboard, go to the Developer Dashboard.
Choose Open on the default test account to access the Sandbox Seller Dashboard.
Choose Transactions.
Deploy the application to production
In this walkthrough, you used the Sandbox environment to test the payment form using a fake credit card number. This section explains how you deploy the application in production by doing the following:
Replace the Sandbox access token and application ID with a production access token and application ID.
Update your code to send requests to Square production endpoints.
Take payments with a valid credit card. In production, Square actually charges the card.
To deploy the preceding walkthrough in production, do the following:
Get production application credentials.
In the Get Sandbox application credentials section, you obtained Sandbox credentials. Follow the steps to open the Developer Dashboard, but this time choose Production mode, and then copy the production application ID and access token.
Note
This walkthrough assumes that your account is activated to accept payments. If not, you need to activate the account. If the Credentials tab in the Developer Dashboard indicates that account activation is required, follow the steps to activate the account. After activation, you can start taking payments.
Update script references.
In the ADD SCRIPT REFERENCES section, you added script references in index.html. Update the domain string in the JavaScript reference from
js.squareupsandbox.com
tojs.squareup.com
.Provide your production application ID.
SqPaymentForm
requires a valid application ID to return a payment token. In the Provide your application ID section, you provided a Sandbox application ID. Update the code by providing your production application ID.Configure your backend server to use a production access token.
In the Configure the backend with your access token section, you provided a Sandbox access token. Replace it with the production access token.
When you have completed these steps, your application is ready to run in production.
If you want to test the application in a production environment (squareup.com
), you must use an actual payment card. Note that Square actually charges payment cards in production so if you must test in production, charge minimum amounts.
Shopping cart example
The previous sections show you the client and server code to integrate the payment form. These isolated examples are best understood when seen in the context of a real-world shopping cart example.
Note that the example code for the payment form client in this topic does not send the amount to charge along with the payment token, idempotency key, and location ID. This is because payment amounts should always be provided by the business logic that your application runs on the backend.
For a shopping cart example that uses the payment form, see Order-Ahead Sample Application. This quick start sample builds a shopping cart with the Catalog API, creates an order with the Orders API, and collects a payment card with the payment form.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.