Home

Square hosted checkout workflow

The Square Checkout API provides a pre-built UI solution for verifying purchase details and taking payments. When you build a solution using the Checkout API, a buyer places an order on your website. When the buyer is ready to checkout, send a checkout request to Square from your server. In the request, include order information and other optional data that you can pre-populate on the checkout page.

After receiving the request, Square pre-builds the checkout page and returns a link to that page to your server. This pre-built checkout page is hosted on Square servers. After the buyer provides valid payment information on the checkout page, Square processes the payment.

In order to do this, we should provide a controller action that will receive the order and send the relative payload to the square Checkout API, it will return a URL like:

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

that must be returned to the response, so the caller will redirect the user to that URL. Then square will take all the checkout information from the user through its checkout flow, and when it's done it will redirect the user to the provided redirectURL(That can be defined on PaymentMethod).

When the order is placed, Square sends an order.updated webhook which should be handled by our application. The related action should retrieve the Square order information by the order_id and update the order information on the Spree::Order.

This is given order.updated payload:

{
    "merchant_id": "MLYT1V3XJD55X",
    "type": "order.updated",
    "event_id": "c4b39f8a-78d7-4c37-adee-d2cef0d3b620",
    "created_at": "2021-10-22T09:03:11Z",
    "data": {
        "type": "order",
        "id": "046fNWrp7I99rZPPfPFSklb8k2bZY",
        "object": {
            "order_updated": {
                "created_at": "2021-10-22T08:59:27.116Z",
                "location_id": "LC4CZYM89JST5",
                "order_id": "046fNWrp7I99rZPPfPFSklb8k2bZY",
                "state": "COMPLETED",
                "updated_at": "2021-10-22T09:03:09.000Z",
                "version": 4
            }
        }
    }
}