Web Payments Quickstart

Quickstart for using Square's Web Payments SDK

• Web Payments SDK Overview.
• API Documentation.

Getting Started

Start by cloning this repository.

git clone https://github.com/square/web-payments-quickstart
cd web-payments-quickstart

Install Node.js which will include npm. This repository contains an .nvmrc file if you use nvm to manage your node versions.

Then, to install dependencies run:

npm install

Run the development server.

npm run dev

Finally, open http://localhost:3000.

Credentials

Before you can take a payment, you'll need to configure your developer credentials which can be found in the Developer Dashboard.

Copy .env.exampleto .env.sandbox

cp .env.example .env.sandbox

Define SQUARE_ACCESS_TOKEN with your Sandbox Access Token from the Developer Dashboard.

SQUARE_ACCESS_TOKEN=eX@mpl3_t0k3n

Restart your server to use this new value.

Each payment method HTML file in public/examples/ must be configured with your Square credentials.

1. Get your credentials from the Developer Dashboard:

   • Application ID: Found in the Credentials tab (left panel)
   • Location ID: Found in the Locations tab (left panel)

2. Update the placeholders in each HTML file (e.g., card-charge.html, apple-pay.html, google-pay.html, ach.html, etc.)

   const appId = '{APPLICATION_ID}'; // Replace with your Application ID
   const locationId = '{LOCATION_ID}'; // Replace with your Location ID

Remember: Do not add your credentials to git!

Development

Setup

When contributing to this project, you'll want to use the version of Node as defined by .nvmrc. You can use nvm to install the correct version:

nvm install $(cat .nvmrc)

Follow the "Getting Started" instructions above to install dependencies and verify your local server starts properly.

Testing

You can run all linters, tests, and builds like CI with npm test.

Linting

You can run all linters with npm run lint.

ESLint

ESLint analyzes the code to find and fix problems. We use eslint-plugin-square for out-of-the-box configuration.

npm run lint:eslint

Fixing warnings and errors automatically

ESLint can sometimes fix warnings and errors automatically for you with its --fix option.

npm run lint:eslint --fix

Prettier

Prettier is an opinionated code formatter. We use @square/prettier-config for those opinions.

npm run lint:prettier

Fixing code style issues

If after running npm run lint:prettier you get a warning like, "Code style issues found in the above file(s). Forgot to run Prettier?", you can have Prettier fix them.

npm run lint:prettier:fix

Continuous Integration

GitHub Actions is used for our CI/CD workflows. See .github/workflows for details.

License

Copyright 2021 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.