Menu Apps
Manage Apps

Getting started with the Payment API

Square's e-commerce API lets merchants accept online payments from a website. Payments processed online show up in a Square merchant's dashboard, just like the payments they process in person with a Square reader.

The e-commerce API supports most credit cards (see this article for details). Square gift cards are currently not supported.

How it works

An e-commerce payment involves the following steps:

Ecommercepayments
  1. You include a small Javascript library on your webpage. This library embeds a secure credit card form on the page when it loads. This form is called the SqPaymentForm.
  2. A buyer enters their card information into the fields of the SqPaymentForm and indicates that they are ready to pay.
  3. Your webpage obtains a card nonce from the SqPaymentForm. This is a one-time-use token that expires in 24 hours. Your page submits the card nonce to your application's server, along with the amount to charge.
  4. Your application's server sends the card nonce, along with the other details of the payment, to the e-commerce API's Charge endpoint. Square responds with the result of the payment.
  5. Your application's server sends the result of the payment back to your webpage.
  6. Your webpage displays the result of the payment to the buyer.

Handling card information responsibly

The Payment Card Industry Data Security Standard (PCI DSS) defines important security requirements for the storage, processing, and transmission of payment card information (card numbers, cardholder names, and so on). To conform to these requirements, you must never store, process, or transmit payment card information.

When a buyer enters their card information into the SqPaymentForm, use it only to generate a card nonce that you send to your application's server. When you send the card nonce to the Charge endpoint, Square takes care of processing and transmitting the card information for you. Under no circumstances should a buyer's confidential card information reach your application's server.

Development steps

Step 0: Complete your Square account and application registration

Make sure you've completed all of the steps in Square APIs: Getting Started before you begin developing with the e-commerce API.

Step 1: Embed the SqPaymentForm on your webpage

Read Embedding the payment form to learn how.

Step 2: Send the card nonce to the Charge endpoint from your server

You can communicate with the e-commerce API with your favorite REST library, or you can use one of Square's provided client libraries. Read the version of Processing a payment that corresponds to your preference:

Step 3: Learn how to store cards on file and other customer information (optional)

Read Saving customer information for details.

Chargeback protection and the e-commerce API

Square provides chargeback protection to its merchants for qualifying transactions. In order for an e-commerce payment to potentially qualify for chargeback protection, you must provide the following parameters in your request to the Charge endpoint:

  • buyer_email_address
  • At least one of billing_address or shipping_address

Was this page helpful?