Checkout API

Manage Checkout

The Checkout API (see Checkout API Overview) provides endpoints to manage the checkout pages you created. You can update, retrieve, or delete the checkout pages.

Link to section
Update a payment link

You can use the UpdatePaymentLink endpoint to update the following payment_link fields.

description.
checkout_options. You should specify the entire CheckoutOptions object in the update request. If you specify only specific fields, the update operation deletes fields not included in the request.
pre_populated_data. You only specify the PrePopulatedData fields that you want to update (or add). If a field you provided in the request does not exist, it gets added.

You cannot update the order_id, version, URL, or timestamp fields.

In the following example, you create a checkout page and then call UpdatePaymentLink to apply the updates.

Create 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
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

curl https://connect.squareupsandbox.com/v2/online-checkout/payment-links \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -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}"
    },
    "pre_populated_data": {
      "buyer_email": "[email protected]",
      "buyer_phone_number": "1-415-555-1212",
      "buyer_address": {
        "address_line_1": "1455 MARKET ST #600",
        "country": "US",
        "administrative_district_level_1": "CA",
        "locality": "San Jose",
        "postal_code": "94103"
      }
    },
    "checkout_options": {
      "allow_tipping": true,
      "ask_for_shipping_address": true,
      "custom_fields": [
        {
          "title": "Special Instructions"
        },
        {
          "title": "Would you like to be on mailing list"
        }
      ]
    }
  }'

The following is an example response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

{
  "payment_link": {
    "id": "OTKXE56AZGRBPAN4",
    "version": 1,
    "order_id": "m1rS3y9B95BWRTVJVs9K3iJD4yLZY",
    "checkout_options": {
      "allow_tipping": true,
      "custom_fields": [
        {
          "title": "Special Instructions",
          "uid": "N3W4FIWOAGI7GMYV62MQ7MQ3"
        },
        {
          "title": "Would you like to be on mailing list",
          "uid": "J7ETDA6UANCFB3UIXJP5AGL6"
        }
      ],
      "ask_for_shipping_address": true
    },
    "pre_populated_data": {
      "buyer_email": "[email protected]",
      "buyer_phone_number": "+14155551212",
      "buyer_address": {
        "address_line_1": "1455 MARKET ST #600",
        "locality": "San Jose",
        "administrative_district_level_1": "CA",
        "postal_code": "94103",
        "country": "US"
      }
    },
    "url": "https://sandbox.square.link/u/J1lWcEhY",
    "created_at": "2022-04-22T02:50:39Z"
  }
}

Update the following fields:
- description. Add a description.
- checkout_options. Specify a new custom_fields ("Very Special Instructions"). You verify that both the existing custom fields are deleted.
- pre_populated_data. Specify only the buyer_email and address_line_1 fields. You verify that all other fields are preserved.
- Specify fields_to_clear to remove checkout_options.allow_tipping.

Run the following UpdatePaymentLink request to apply the updates:

Update Payment Link

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

curl https://connect.squareupsandbox.com/v2/online-checkout/payment-links/{id} \
  -X PUT \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "payment_link": {
      "version": 1,
      "description": "updated  description",
      "checkout_options": {
        "custom_fields": [
          {
            "title": "Very special Instructions "
          }
        ]
      },
      "pre_populated_data": {
        "buyer_email": "[email protected]",
        "buyer_address": {
          "address_line_1": "1455 MARKET ST #6600"
        }
      }
    },
    "fields_to_clear": [
      "checkout_options.allow_tipping"
    ]
  }'

Note that fields_to_clear is an array where you provide a comma-separated list of fields to delete. For example:

"fields_to_clear": [
   "checkout_options.allow_tipping", 
   "pre_populated_data.buyer_address"
]

This deletes the allow_tipping field from checkout_options and the entire buyer_address from pre_populated_data. To delete the entire checkout_options, specify the following:

"fields_to_clear": [
   "checkout_options
]

Link to section
Retrieve payment links

You can retrieve a specific payment link by ID or all the payment links in the account. The Checkout API provides the RetrievePaymentLinks and ListPaymentLinks endpoints. Try using API Explorer to test these endpoints.

Link to section
Delete a payment link

You can use the DeletePaymentLinks endpoint to delete a payment link you created.

Delete Payment Link

curl https://connect.squareupsandbox.com/v2/online-checkout/payment-links/{id} \
  -X DELETE \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

After receiving the request, the endpoint sets the corresponding order state to CANCELED and deletes the checkout link.

{
  "id": "KFLXPQROJALW56ZX",
  "cancelled_order_id": "6nJTzvMv7nA28JSKAgDpxlg3vgFZY"
}

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

Manage Checkout

Link to section Update a payment link

Link to section Retrieve payment links

Link to section Delete a payment link

On this page

Link to section
Update a payment link

Link to section
Retrieve payment links

Link to section
Delete a payment link