You are viewing an old version of the 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

PAYMENTS_WRITE

ORDERS_READ

ORDERS_WRITE

Guide

Checkout API Overview Try in API Explorer

Request Body

Example code

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

POST /v2/online-checkout/payment-links

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"
    }
  }'

{
  "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.	>

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