Describes the Checkout API and how it works in developing Square-hosted checkout pages.
Take 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 Web Payments SDK 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 on 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 a link to that page to your server. The unique URL has the following format:

    This prebuilt checkout page (also referred to as a 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 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.

      A graphic showing the Checkout API order details page with an itemized list and a place to enter personal email and payment information.

    • If the original checkout request included other optional information, such as shipping information, the checkout page includes 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.

      A graphic showing the Checkout API checkout page, with purchase itemization and Apple Pay and Google Pay as payment options.

  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 seller application does not list its own redirect page, Square redirects the customers to a Square-provided payment confirmation page. An example is shown:

    A graphic showing the Checkout API confirmation page, with the order details and totals.

Important

If your application backend needs to get access to the Order object that Square created for the checkout, you need to provide your own redirect URL and page. When Square posts the confirmation to your redirect page, you can get the Order.ID from the transactionId query parameter, as shown in this example: http://www.example.com/order-complete?checkoutId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx.

Use the RetrieveOrder endpoint and use the value of transactionID in the order_id path parameter of RetrieveOrder.

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

  • The Checkout API is supported in the following countries:

    • Australia

    • Canada

    • Japan

    • United States

    • United Kingdom

  • 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, and Java).

  • Applications that use OAuth need PAYMENTS_WRITE and ORDERS_WRITE permissions.

  • The order confirmation email cannot be customized.

Prepopulate customer information Permalink Get a link to this section

Checkout API can record shipping information with the transaction. If your Checkout flow collects shipping information and you've already collected the information earlier in the workflow, we recommend pre-populating that data for a more seamless experience for your customer.

Before you start Permalink Get a link to this section

  • You have a Square account enabled for payment processing. If you have not enabled payment processing on your account (or you are not sure), visit squareup.com/activation.

  • You must have already collected customer information or have a way to collect it before creating this Checkout.

  • Your website hosting must support dynamic pages with server-side processing (e.g., code written with PHP, Ruby, ASP, or Java). Hosting solutions that support only HTML pages cannot use Square Checkout at this time.

Step 1: Create a prepopulated Address object Permalink Get a link to this section

Create an Address object and fill it with your previously collected address information, then set that Address object as pre_populate_shipping_address.

Step 2: Set your CreateCheckout request fields Permalink Get a link to this section

Make sure your CreateCheckout request object has ask_for_shipping_address set to true and populate the pre_populate_buyer_email with the customer email address.

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.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.