Checkout API

What It Does

Take payments with a prebuilt payment flow hosted by Square.

This guide provides step-by-step instruction for integrating with the Checkout API.

Square Checkout API is a prebuilt solution for taking payments with a secure payment form hosted by Square. Checkout API simplifies online payments with next business day deposits, PCI-compliant payments, and SSL support.

Requirements and limitations
Permalink Get a link to this section

  • 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.

Product components
Permalink Get a link to this section

The Checkout API is a RESTful web service and payment UI hosted on Square servers. To take payments with Checkout, merchant sites need to send a request containing order information to the CreateCheckout endpoint and receives a URL to a payments processing page hosted by Square. Once the customer completes their transaction, they will be directed to the payment confirmation page.

The Checkout URL
Permalink Get a link to this section

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.

Important

Checkout URLs expire after 180 days.

Payments processing page
Permalink Get a link to this section

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.

The Checkout API detects support for Apple Pay and Google Pay on the hosting device and then a payment button is shown for each supported payment service.

checkout-digitalwallet

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
Permalink Get a link to this section

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

checkout-screen-02

Security best practices
Permalink Get a link to this section

SSL
Permalink Get a link to this section

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.

Verify payment results
Permalink Get a link to this section

Square strongly recommends verifying payment results to guard against order spoofing. To verify payments, applications can query Square's GetPayment endpoint for the payment details and confirm the order ID, checkout ID, and payment totals match the expected values.

For more information on how to verify payment results, please see the Square Checkout Setup guide.

Get started

Use the build guide to integrate with the Checkout API.