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 - The optional description of the payment_link object.
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 doesn't 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-08-16' \
  -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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

{
  "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"
  },
  "related_resources": {
    "orders": [
      {
        "id": "C0DMgui6YFmgyURVSRtxr4EShheZY",
        "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"
        }
      }
    ]
  }
}

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.
- fields_to_clear - Specify the field 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-08-16' \
  -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-08-16' \
  -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.

Docs

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

Docs

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