Online Payments

Checkout API

The Checkout API lets you verify payment details and take payments with a prebuilt payment flow hosted by Square.

Overview Permalink Get a link to this section

Important

If you are developing a new application, instead of using the Checkout API option, you should 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 the Square Checkout API involves the following steps:

  1. A buyer places an order in your website.

  2. When the buyer is ready to check out, 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 prepopulate on the checkout page.

  3. After 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 prebuilt checkout page (also referred to as payment processing page) is hosted on Square servers.

  1. 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 performs data entry validation, such as verifying that all the required fields are populated and verifying that the card expiration date is valid. The following are example checkout pages:

    • On this page, the customer sees order details as an itemized list and a 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. If the Checkout API detects support for Apple Pay and Google Pay on the hosting device, the checkout page shows a payment button for each supported payment service.
      checkout-digitalwallet

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

  3. Square redirects the customer to the checkout confirmation page. If the seller application does not list its own redirect page, Square redirects the 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, colors, and Square branding), and you follow a strict pattern: the 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 these totals, you need to add code to perform these 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 (such as PHP, Ruby, ASP, and Java).

  • Applications that use OAuth need 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. For more information, see Square Connect API Examples.