Online Payments

Checkout API

Take payments with a prebuilt payment flow hosted by Square.

Overview
Permalink Get a link to this section

The Square Checkout API provides a pre-built UI solution for verifying purchase details and taking payments.

Important

If you are developing a new application, instead of the Checkout API option, we recommend you explore the payment processing option in which you integrate the fully customizable Square payment form in your own web checkout experience. For more information, see Online Payment Options.

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

  1. A buyer places an order in your website.

  2. When the buyer is ready to checkout, you send a checkout request to Square from your server. In the request, you include order information and other optional data that you might choose to pre-populate on the checkout page.

  3. Upon receiving the request, Square prebuilds the checkout page, and returns to your server a link to that page. The unique URL has the following format:

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

    This pre-built checkout page (also referred to as payment processing page) is hosted on Square servers.

  4. Your application server sends the Checkout URL to your frontend, which redirects the customer to that URL, and the checkout page appears prepopulated with the transaction information. The checkout UI does data entry validation such as verify all the required fields are populated and verify card expiration date is valid. The following are example checkout pages:

    • On this page the customer sees order details as itemized list and place to enter personal email and payment information.
      checkout-screeshot-example1

    • If the original checkout request included other optional information such as shipping information the checkout page include the information. Also, if the Checkout API detects support for Apple Pay and Google Pay on the hosting device, then checkout page shows payment button for each supported payment service.
      checkout-digitalwallet

  5. After the buyer provides valid payment information on the checkout page, Square processes the payment.

  6. Square redirects the customer to the Checkout confirmation page. If the merchant application does not list its own redirect page, Square redirects customers to a Square-provided payment confirmation page. An example is shown: checkout-screen-02

The Checkout API payment processing solution works with a couple of caveats. For example, you still need a server, you cannot customize the UI (fonts, color and Square branding cannot be changed), and you also follow a strict pattern: buyer places an order and the Checkout API confirms the order and allows the buyer to pay for it.

Requirements and limitations
Permalink Get a link to this section

  • Checkout URLs expire after 180 days.

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

Examples
Permalink Get a link to this section

Checkout API examples are available in GitHub. For each example, the README provides step-by-step instructions for you to download and run the application. It also provides For more information, see Square Connect API Examples.