Take Payments

Checkout API Overview

Accept online payments with a prebuilt payment flow hosted by Square.

Square Checkout lets merchants accept online payments for supported payment types using a checkout workflow hosted on squareup.com that simplifies the process of accepting online payments by providing, Chargeback protection for qualifying transactions, Next business day deposits, PCI compliance, and SSL support.

The Checkout UI

Square Checkout has two main screens: payment processing and payment confirmation.

The payment processing screen is where customers either enter credit card details or use Apple Pay (US merchants only) to place their order. Optionally, buyers can confirm their shipping information:

Checkout screen 01

The payment confirmation page is only displayed if you opt not to redirect the customer to your own confirmation page:

Checkout screen 02

Technical Overview


To use Square Checkout on your website, you must be using a hosting solution that allows you to create dynamic pages that support server side scripting (e.g., PHP, Ruby, ASP, Java). If your hosting solution only supports HTML, you cannot use Square Checkout at this time.

How it works

Square Checkout is a RESTful web service and payment UI, hosted on Square’s servers, for collecting and processing payment information. To take payments with Checkout, merchant sites need to add code that sends order information to Square and (optionally) verifies the result.

In general, completing an order with Square Checkout involves the following steps:

  1. Merchant - Create a POST request:
    1. Package the order information as a JSON message. NOTE: Currently, Square Checkout cannot calculate shipping costs or taxes dynamically, those totals must be provided in the POST request as line items in the order.
    2. Add an authorization token to the header.
  2. Merchant - Send the generated POST request to Square Checkout and process the response:
    1. Save the returned checkout ID.
    2. Automatically redirect the customer to the returned Checkout page URL.
  3. Customer - Provide payment details using the Square Checkout UI.
  4. Square Checkout - Process the transaction and sends email confirmation to merchant and customer.
  5. Merchant - Verify the transaction results.

Which would look something like this:

Process flow

Once payment processing completes, transaction and buyer details can be accessed via the Square Dashboard.

Create the POST request

Square Checkout is a RESTful endpoint. We recommend that merchants use the Square Connect SDK to send/receive information to Square endpoints, but any site capable of sending information as a JSON message in the following format can use Checkout to process payments:

  "redirect_url": "{{URL TO CONFIRMATION PAGE}}",
  "idempotency_key": "{{UNIQUE STRING FOR THIS TRANSACTION}}",
  "ask_for_shipping_address": {{true or false}},
  "merchant_support_email": "{{SUPPORT EMAIL ADDRESS}}",

  "order": {
    "reference_id": "{{STORE ORDER ID}}",
    "line_items": [

      // List each item in the order as an individual line item
        "name": "{{ITEM_1 NAME}}",
        "quantity": "{{ITEM_1 QUANTITY}}",
        "base_price_money": {
          "amount": {{ITEM_1 COST IN BASE MONETARY UNIT}},
          "currency": "{{ITEM_1 CURRENCY USED}}"
        discounts: [
            "name": "{{ITEM_1_DISCOUNT NAME}}",
            "amount_money": {
              "amount": {{ITEM_1_DISCOUNT AMOUNT}},
              "currency": "{{ITEM_1_DISCOUNT CURRENCY USED}}"
        "taxes": [
           "name": "{{ITEM_1_TAX NAME}}",
           "percentage": "{{ITEM_1_TAX PERCENTAGE}}",
           "type": "{{ITEM_1_TAX TYPE}}"
        "name": "{{ITEM_2 NAME}}",
        "quantity": "{{ITEM_2 QUANTITY}}",
        "base_price_money": {
          "amount": {{ITEM_2 COST IN BASE MONETARY UNIT}},
          "currency": "{{ITEM_2 CURRENCY USED}}"
      . . .
        "name": "{{ITEM_N NAME}}",
        "quantity": "{{ITEM_N QUANTITY}}",
        "base_price_money": {
          "amount": {{ITEM_N COST IN BASE MONETARY UNIT}},
          "currency": "{{ITEM_N CURRENCY USED}}"
        discounts: [
           "name": "{{ITEM_N_DISCOUNT NAME}}",
           "percentage": "{{ITEM_N PERCENTAGE USED}}"
  "pre_populate_buyer_email": "{{CUSTOMER CONTACT INFORMATION: EMAIL}}",
  "pre_populate_shipping_address": {
    "address_line_1": "{{SHIPPING ADDRESS, LINE 1}}",
    "address_line_2": "{{SHIPPING ADDRESS, LINE 2}}",
    "locality": "{{SHIPPING CITY/TOWNSHIP/ETC}}",
    "administrative_district_level_1": "{{SHIPPING STATE/PROVINCE/ETC}}",
    "postal_code": "{{SHIPPING POSTAL CODE}}",
    "country": "{{SHIPPING COUNTRY}}",
    "first_name": "{{CUSTOMER FIRST NAME}}",
    "last_name": "{{CUSTOMER LAST NAME}}"
      "location_id":  "{{RECIPIENT_LOCATION_ID}}",
      "description":  "{{DESCRIPTION}}",
        "amount_money" : {
          "amount": {{SPLIT AMOUNT IN BASE MONETARY UNIT}},
          "currency": "{{CURRENCY USED}}"

The key elements of the message are:

  • redirect_url - Square Checkout will send the customer to this URL after a successful transaction or in the event of an unrecoverable error. If you do not provide a redirect url, Square Checkout will display an order confirmation page on your behalf.
  • idempotency_key - The idempotency key is used to avoid processing the same order more than once. It can be any valid string but must be unique for every order sent to Square Checkout for a given location.
  • reference_id - This is the identifier for the order (e.g., an order number) generated by your shopping cart solution. Square Checkout will save this identifier with the transaction information so you can link order information from your shopping cart solution with the payment processing information from Square Checkout.
  • order.line_items - Each item in the order must be listed as a line item in the order with an appropriate price and quantity.
  • line_items.discounts and order.discounts - Discounts applied to the transactions at the line item or order level. Line item discounts are applied to the purchase item before calculating the subtotal while order-level discounts are distributed across all line items in the order. Discounts are always applied before calculating any applicable taxes.
  • line_items.taxes and order.taxes - Taxes applied to the transaction at the line item or order level. Line item taxes are applied to the specific purchased item while order-level taxes are applied to all purchases in the order.

To process payments with Square Checkout you also need a valid location ID and authorization token. Valid authorization tokens include:

The location ID is used to construct the full Checkout endpoint URL and to associate payment with a particular store belonging to the merchant account. The authorization token lets Square Checkout know that the transaction is authorized for the merchant account associated with that location ID.

The additional_recipients field is only available for apps using OAuth. To learn more about splitting transactions for multi-party transactions, see the Multi-party Transactions Overview and Multi-party Transactions Setup

Send the POST request to Square Checkout

The full Checkout URL for a given location ID is:


When Checkout receives a merchant request at that URL it:

  • Authenticates the authorization token.
  • Authenticates the location ID.
  • Verifies the location ID belongs to the merchant account indicated by the authorization token and the location is able to create payments and orders.
  • Initializes a new transaction with the order information.
  • Returns a new checkout ID and a checkout URL of the form

When the merchant site receives the response it saves the checkout ID with the local order information then redirects the customer to the Square-hosted Checkout URL.

Provide payment details using the Square Checkout UI

When the customer is redirected to Square Checkout, they are presented with a screen where they can review the order details as an itemized list and enter their payment information. If the original POST request included shipping information, those fields are pre-populated for the customer.

Data entry validation in the Checkout UI includes:

  • Proper formatting for email address.
  • Proper formatting for credit card number.
  • Credit card expiration date not in the past.
  • All required fields populated.

Process the transaction

Once the payment card information is submitted, Square Checkout will try to authorize and capture payment. In the event of a recoverable error (e.g., the card is declined), the customer is prompted to correct their information.

Once payment is processed, Checkout sends two verification emails: one to the customer at the provided address and one to the merchant at the email address associated with their Square account. The transaction and buyer details can also be accessed through the Square Dashboard.

If the original POST request included a redirect URL, the customer is automatically sent to that URL, otherwise, they are presented with a Square Checkout confirmation page.

Verify transaction results

Square strongly recommends setting a redirect URL and verifying transaction results to guard against order spoofing. Checkout will append the transaction ID, checkout ID, and store-generated order ID to the redirect URL to facilitate verification. In order to verify the transaction results, merchants should query Square’s Transaction endpoint for the transaction details and confirm the store-generated order ID, checkout ID, and transaction totals match the expected values. For more information on how to verify transaction results, please see the Square Checkout Setup guide.

Checkout API Setup >

Ask for help on Stack Overflow or join our Slack channel