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 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
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.
The key elements of the request object:
idempotency_key— Required. 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.
order— Required. Itemized transaction information packaged as an
orderobject. Note that the Checkout API cannot link to existing orders made with the Orders API. Read more about order objects.
redirect_url— Recommended. 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:
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.
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.
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.
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:
- Application frontend collects transaction information
- Application backend sends a
- Square responds with a checkout object that includes an
orderobject and a URL to the Checkout form.
- Application backend sends the checkout URL to its frontend, which redirects the customer to that URL. The Checkout form appears prepopulated with transaction information.
- Customer provides payment details using the Square Checkout UI hosted by Square.
- Square attempts to authorize and capture the payment. If there is an error, the Square Checkout form prompts the customer to correct their information.
- Square redirects the customer to the Checkout confirmation page.
Once payment processing completes, transaction and buyer details can be accessed in the Square Dashboard.
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.