Documentation Manage Apps

Square Checkout Overview

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:

Summary

  • Languages supported: PHP, C#, Ruby, Python, HTTP
  • Platform: Web
  • Implementation: SDK, SaaS

Additional Resources:

The Checkout UI

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

The payment processing screen is where customers enter their credit card details and (optionally) 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

Requirements

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.

Square Checkout in a nutshell

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:

Example square checkout 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}}"
        }
      },
      {
        "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}}"
        }
      },
    ]
  },

  "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}}",
    "first_name": "{{CUSTOMER FIRST NAME}}",
    "last_name": "{{CUSTOMER LAST NAME}}"
  }
}

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 (including taxes and shipping costs) must be listed as a line item in the order with an appropriate price and quantity.

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.

Send the POST request to Square Checkout

The full Checkout URL for a given location ID is:

connect.squareup.com/v2/locations/{{location-id}}/checkouts

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
    https://connect.squareup.com/v2/checkout?c={{CHECKOUT_ID}}&l={{LOCATION_ID}}

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 (coming soon).

Additional Resources