Learn how to create a Square-hosted quick pay checkout page by only specifying the name and price (without having to specify the Order object).
Checkout API

Quick Pay Checkout

An application can generate a quick pay checkout page (see Checkout API Overview) to allow a seller to sell an ad hoc item and get paid (without specifying an Order object in the request). The application can then embed the link in the application or send it to the buyer using, for example, email or social media.

The CreatePaymentLink request requires only the item name, price, and seller location. The following example request creates a quick pay checkout page for $125 for auto detailing:

Create Payment Link
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
curl https://connect.squareupsandbox.com/v2/online-checkout/payment-links \
  -X POST \
  -H 'Square-Version: 2022-06-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "quick_pay": {
      "name": "Auto Detailing",
      "price_money": {
        "amount": 12500,
        "currency": "USD"
      },
      "location_id": "{LOCATION_ID}"
    }
  }'

After receiving the requests, Square creates the following:

  • An Order. The name and price_money map to the order line item name and base_price_amount. Note that the state of the order created is DRAFT. After the buyer pays for the order, the state changes to OPEN.

  • A PaymentLink object. It provides, among other things, order_id and URL to the checkout page that Square renders when requested.

An example response is shown:

Note the following about information in the response:

  • Applications can use the order ID to access the order using the Orders API (RetrieveOrder endpoint).

  • The seller can send or display the checkout page to the buyer to take payment. The buyer can use the payment link only once.

The following describes the buyer experience and relevant updates that occur after the buyer pays for the order. Note that the screenshots shown reflect the buyer experience in production. In the Sandbox, you can take a payment and verify it, but the UI experience is not the same as in production.

  1. The buyer opens the URL, which opens the Square-hosted checkout page where the buyer can make a payment. The following is an example screenshot.

    A graphic showing the basic checkout page.

    Note the following about the checkout page:

    • The checkout page shows the primary business name as configured in the seller's Square account.

    • If the buyer device (for example, a browser on your computer or a mobile phone) supports Apple Pay or Google Pay, the checkout page shows the payment button that best suits that browser. For example, show the Apple Pay option when the buyer is using Safari. For more information about available payment methods, see AcceptedPaymentMethods and Guidelines and Limitations.

  2. Square processes the buyer's payment as follows:

    • Displays the order confirmation page. The following is an example Square-provided confirmation page:

      A screenshot showing an example Square-provided confirmation page.

      If you provided a redirect URL in the request, Square redirects the buyer to that page instead.

    • Sends a Square receipt to the email address that the buyer provided during checkout.

    • Sends a "payment received" email notification to the seller. The notification is sent to the primary email address associated with their Square account. Note that sellers can enable or disable email notifications in the Seller Dashboard by choosing Online Checkout, and then choosing General under Settings.

    • Updates the Order as follows:

      • Changes state from DRAFT to OPEN.

      • Adds a Tender object to the order. It describes the tender used to pay for the order. Note that the Tender.id identifies the associated Payment object that was created. You can use the Payments API to access the payment.

    • After the order is paid by the buyer, the order is shown in Order Manager in the Seller Dashboard. For example, you can open the Seller Dashboard, choose Orders, and review the order ("state": "OPEN").

Related topics Permalink Get a link to this section

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