Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Checkout

  • Retrieve location settings

  • Update location settings

  • Retrieve merchant settings

  • Update merchant settings

  • List payment links

  • Create payment link

  • Delete payment link

  • Retrieve payment link

  • Update payment link

  • Webhooks

  • online_checkout.location_settings.updated

  • online_checkout.merchant_settings.updated

<- Checkout API

Checkout API

All versions ->

Create payment link

POST

 /v2/online-checkout/payment-links

Creates a Square-hosted checkout page.

Applications can share the resulting payment link with their buyer to pay for goods and services.

Permissions:ORDERS_READ, ORDERS_WRITE, PAYMENTS_WRITE

Guide

Checkout API Overview

Try in API Explorer
Link to section

Request body

Example code

Link to section

idempotency_key

string

A unique string that identifies this CreatePaymentLinkRequest request. If you do not provide a unique string (or provide an empty string as the value), the endpoint treats each request as independent.

For more information, see Idempotency.

Max Length
192
Link to section

description

string

A description of the payment link. You provide this optional description that is useful in your application context. It is not used anywhere.

Max Length
4096
Link to section

quick_pay

Describes an ad hoc item and price for which to generate a quick pay checkout link. For more information, see Quick Pay Checkout.

Link to section

order

Describes the Order for which to create a checkout link. For more information, see Square Order Checkout.

Link to section

checkout_options

Describes optional fields to add to the resulting checkout page. For more information, see Optional Checkout Configurations.

Link to section

pre_populated_data

Describes fields to prepopulate in the resulting checkout page. For more information, see Prepopulate the shipping address.

Link to section

payment_note

string

A note for the payment. After processing the payment, Square adds this note to the resulting Payment.

Max Length
500
Link to section

Response fields

Link to section

errors

Any errors that occurred during the request.

Link to section

payment_link

The created payment link.

Link to section

related_resources

The list of related objects.

Link to section

Examples

All versions ->

POST /v2/online-checkout/payment-links
curl https://connect.squareup.com/v2/online-checkout/payment-links \ -X POST \ -H 'Square-Version: 2026-09-16' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "idempotency_key": "cd9e25dc-d9f2-4430-aedb-61605070e95f", "quick_pay": { "name": "Auto Detailing", "price_money": { "amount": 10000, "currency": "USD" }, "location_id": "A9Y43N9ABXZBP" } }'

Response JSON

{ "payment_link": { "id": "PKVT6XGJZXYUP3NZ", "version": 1, "order_id": "o4b7saqp4HzhNttf5AJxC0Srjd4F", "url": "https://square.link/u/EXAMPLE", "long_url": "https://checkout.square.site/EXAMPLE", "created_at": "2022-04-25T23:58:01Z" }, "related_resources": { "orders": [ { "id": "o4b7saqp4HzhNttf5AJxC0Srjd4F", "location_id": "{LOCATION_ID}", "source": { "name": "Test Online Checkout Application" }, "line_items": [ { "uid": "8YX13D1U3jO7czP8JVrAR", "name": "Auto Detailing", "quantity": "1", "item_type": "ITEM", "base_price_money": { "amount": 12500, "currency": "USD" }, "variation_total_price_money": { "amount": 12500, "currency": "USD" }, "gross_sales_money": { "amount": 12500, "currency": "USD" }, "total_tax_money": { "amount": 0, "currency": "USD" }, "total_discount_money": { "amount": 0, "currency": "USD" }, "total_money": { "amount": 12500, "currency": "USD" } } ], "fulfillments": [ { "uid": "bBpNrxjdQxGQP16sTmdzi", "type": "DIGITAL", "state": "PROPOSED" } ], "net_amounts": { "total_money": { "amount": 12500, "currency": "USD" }, "tax_money": { "amount": 0, "currency": "USD" }, "discount_money": { "amount": 0, "currency": "USD" }, "tip_money": { "amount": 0, "currency": "USD" }, "service_charge_money": { "amount": 0, "currency": "USD" } }, "created_at": "2022-03-03T00:53:15.829Z", "updated_at": "2022-03-03T00:53:15.829Z", "state": "DRAFT", "version": 1, "total_money": { "amount": 12500, "currency": "USD" }, "total_tax_money": { "amount": 0, "currency": "USD" }, "total_discount_money": { "amount": 0, "currency": "USD" }, "total_tip_money": { "amount": 0, "currency": "USD" }, "total_service_charge_money": { "amount": 0, "currency": "USD" } } ] } }

Error descriptions

400 Bad request

{ "errors": [ { "code": "INVALID_PHONE_NUMBER", "category": "INVALID_REQUEST_ERROR" } ] }