<- Checkout API

Checkout API

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

POST /v2/online-checkout/payment-links

curl https://connect.squareup.com/v2/online-checkout/payment-links \
  -X POST \
  -H 'Square-Version: 2024-11-20' \
  -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"
        }
      }
    ]
  }
}

Create payment link

Request body

Response fields

Error descriptions