• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the 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
PAYMENTS_WRITE
ORDERS_READ
ORDERS_WRITE
Guide
Checkout API Overview
Try in API Explorer
Name Description
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
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
quick_pay
QuickPay

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

order
Order

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

checkout_options
CheckoutOptions

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

pre_populated_data
PrePopulatedData

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

payment_note
string

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

Max Length 500

Response Fields

Name Description
errors
Error [ ]

Any errors that occurred during the request.

payment_link
PaymentLink

The created payment link.

related_resources
PaymentLinkRelatedResources

The list of related objects.

Examples

You are viewing an old version of the API
POST /v2/online-checkout/payment-links
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js
curl https://connect.squareup.com/v2/online-checkout/payment-links \
  -X POST \
  -H 'Square-Version: 2022-11-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",
    "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 INVALID_PHONE_NUMBER

The provided phone number is invalid.

>
400 Bad request INVALID_EMAIL_ADDRESS

The provided email address is invalid.

>
400 Bad request
{
  "errors": [
    {
      "code": "INVALID_PHONE_NUMBER",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}