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.

Requirements and limitations

  • The Checkout API cannot dynamically calculate shipping costs. If your shopping cart solution cannot provide those totals, you will need to add code to perform those calculations.
  • The Checkout page is only available in English at this time.
  • Your hosting solution must be able to support dynamic pages with server side scripting (e.g., PHP, Ruby, ASP, Java).
  • Applications that use OAuth need the PAYMENTS_WRITE and ORDERS_WRITE permissions.

How to use it - Checkout API data model

The Checkout API is a RESTful web service and payment UI hosted on Square's servers. To take payments with Checkout, merchant sites need to add code that sends order information to Square and receives a URL to the Square Checkout UI.

Request object

The key elements of the request object:

  • idempotency_keyRequired. Used to avoid processing the same order more than once. Can be any valid string but must be unique for every order sent to Square Checkout for a given location. Read more about idempotency keys.
  • orderRequired. Itemized transaction information packaged as an order object. Note that the Checkout API cannot link to existing orders made with the Orders API. Read more about order objects.
  • redirect_urlRecommended. The Checkout API 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, The Checkout API will display an order confirmation page on your behalf.

The request object can also include optional data to prepopulate the Checkout form, such as customer email or a second reference ID for third-party shopping cart solutions. Read more about Checkout fields.

The Square Checkout URL

When the Checkout API receives a valid request, it will produce a unique URL with the following format:

https://connect.squareup.com/v2/checkout?c={{CHECKOUT_ID}}&l={{LOCATION_ID}}

When the customer opens this link, they are redirected to the Square payment processing page that is prepopulated with transaction information.

Payments processing page

The payment processing screen is where customers 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.

Checkout screen 01

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.

Payment confirmation page

If the merchant application does not list its own redirect page, Square will direct customers to this payment confirmation page.

Checkout screen 02

Best practices for data

While SSL is not required to use Checkout, Square strongly recommends that merchant sites be SSL certified to reduce the risk of man-in-the-middle attacks. Read more about TLS and HTTPS.

High level process overview

At a high level, completing an order with Square Checkout involves the following steps:

  1. Application frontend collects transaction information
  2. Application backend sends a CreateCheckout request.
  3. Square responds with a checkout object that includes an order object and a URL to the Checkout form.
  4. Application backend sends the checkout URL to its frontend, which redirects the customer to that URL. The Checkout form appears prepopulated with transaction information.
  5. Customer provides payment details using the Square Checkout UI hosted by Square.
  6. Square attempts to authorize and capture the payment. If there is an error, the Square Checkout form prompts the customer to correct their information.
  7. Square redirects the customer to the Checkout confirmation page.

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

Process flow

Best practices for development

Verify transaction results

Square strongly recommends verifying transaction results to guard against order spoofing. To verify transactions, applications can query Square's RetrieveTransaction endpoint for the transaction details and confirm the 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.

Next
Checkout API Setup >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow