Checkout API

Build With Checkout

Integrate with the Checkout API to take payments with a prebuilt payment flow hosted by Square.

Backend
Checkout API

Prerequisites
Permalink Get a link to this section

To use Square Checkout, all of the following must be true:

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

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

We also make the following assumption:

You have read the What It Does page for this product.

Information you need
Permalink Get a link to this section

To use the steps in this guide you need the following information from the Developer Portal:
  • A valid access token. Square recommends testing with sandbox credentials whenever possible. See Square API Access Tokens for more information.
  • An active location ID. Use the Locations API to get locations for a seller. To speed up app development, find and copy a valid Developer Account location ID from the Locations setting page of your Square application in the Developer Dashboard. You can also get a production location ID in the Square Dashboard Locations page for a Square Account.

Step 1: Install the Connect SDK
Permalink Get a link to this section

The Connect SDK provides a helpful wrapper for interacting with our APIs. Though it takes an extra step to install the SDK, it will make interacting with Connect APIs much easier. We will be using the SDK for the rest of this guide.

  1. Follow the Square PHP SDK installation steps to install the SDK. You can clone the SDK directly from Github or you can use Composer, a dependency manager for PHP.

  2. Include the Connect PHP SDK in your file. Remember to change the path depending on where you place the SDK in relation to your other php files.

// Include the Square Connect API resources
require_once(__DIR__ . '/local/path/to/Square/Connect/SDK/autoload.php');

Step 2: Set your application credentials and initialize an API client
Permalink Get a link to this section

Set your application credentials and create an API client for the v2 Sandbox (beta) environment.

//Replace your access token and location ID
$accessToken = 'REPLACE_ME';
$locationId = 'REPLACE_ME';

// Create and configure a new API client object
$defaultApiConfig = new \SquareConnect\Configuration();
$defaultApiConfig->setAccessToken($accessToken);
$defaultApiConfig->setHost("https://connect.squareupsandbox.com");
$defaultApiClient = new \SquareConnect\ApiClient($defaultApiConfig);
$checkoutClient = new SquareConnect\Api\CheckoutApi($defaultApiClient);

Step 3: Create an order for your checkout request
Permalink Get a link to this section

CreateCheckout requests require order information to be packaged as Order objects. We will create an Order object first by creating line items and then by creating the Order object.

For more step by step guidance on creating an Order object, see our Build With Orders guide.

//Create a Money object to represent the price of the line item.
$price = new \SquareConnect\Model\Money;
$price->setAmount(600);
$price->setCurrency('USD');

//Create the line item and set details
$book = new \SquareConnect\Model\CreateOrderRequestLineItem;
$book->setName('The Shining');
$book->setQuantity('2');
$book->setBasePriceMoney($price);

//Puts our line item object in an array called lineItems.
$lineItems = array();
array_push($lineItems, $book);

// Create an Order object using line items from above
$order = new \SquareConnect\Model\CreateOrderRequest();

$order->setIdempotencyKey(uniqid()); //uniqid() generates a random string.

//sets the lineItems array in the order object
$order->setLineItems($lineItems);

Step 4: Add code that creates a CreateCheckout request object
Permalink Get a link to this section

Create a CreateCheckout request object using the PHP SDK. Note that your request requires an idempotency key and the Order object you just made.

We also strongly recommend you use the redirect_url field to redirect your customers back to your store after the Checkout flow. If you do not include a redirect URL in your request, Checkout will present a confirmation page on your behalf and your customers will need to navigate back to your page on their own.

///Create Checkout request object.
$checkout = new \SquareConnect\Model\CreateCheckoutRequest();

$checkout->setIdempotencyKey(uniqid()); //uniqid() generates a random string.
$checkout->setOrder($order); //this is the order we created in the previous step.
$checkout->setRedirectUrl(YOUR_REDIRECT_URL); //Replace with the URL where you want to redirect your customers after transaction. 

Step 5: Send the itemized order to the Square Checkout endpoint
Permalink Get a link to this section

Send your CreateCheckout request and save the result. If successful, the code below will get and print the checkout URL that opens the checkout page. If there's an error, it will print the error response.

try {
    $result = $checkoutClient->createCheckout(
      $locationId,
      $checkout
    );
    //Save the checkout ID for verifying transactions
    $checkoutId = $result->getCheckout()->getId();
    //Get the checkout URL that opens the checkout page.
    $checkoutUrl = $result->getCheckout()->getCheckoutPageUrl();
    print_r('Complete your transaction: ' . $checkoutUrl);
} catch (Exception $e) {
    echo 'Exception when calling CheckoutApi->createCheckout: ', $e->getMessage(), PHP_EOL;
}

Next steps

Integrate the Catalog API to itemize checkout orders with catalog items