Optional Checkout Configurations
The checkout_options
field in the CreatePaymentLink request allows you to add optional fields to the resulting checkout page (see Checkout API Overview). These fields can be used, for example, for tipping options, requesting information from buyers through custom fields, and prepopulating buyer data (such as email address, phone number, and shipping address).
By default, the checkout page doesn't include address fields. The CreatePaymentLink
request must include checkout_options
(see CheckoutOptions) with the ask_for_shipping_address
field set to true
for these fields to appear on the checkout page as shown. This also results in having SHIPMENT
as the order fulfillment type.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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}"
},
"checkout_options": {
"ask_for_shipping_address": true
}
}'
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
{
"payment_link": {
"id": "UO6BJB7EXQOQKIDA",
"version": 1,
"description": "",
"order_id": "0mKB0CULaS8SYRAJXaoIp1SUABZZY",
"checkout_options": {
"ask_for_shipping_address": true
},
"url": "https://sandbox.square.link/u/fTkKKauH",
"created_at": "2022-03-20T19:03:01Z"
},
"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"
}
}
]
}
}
When the buyer opens the checkout page, they must provide their name, phone number, and address. After the buyer provides the information, Square processes the payment and updates the order as follows:
Sets the
state
fromDRAFT
toOPEN
.Updates
Order.fulfillments.shipment_details
to include name, phone number, and address information.
Applications can also prepopulate the buyer's address on the checkout page by adding the pre_populated_data
field in request body as shown:
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
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": "7WQ0KXC8ZSD90"
},
"checkout_options": {
"ask_for_shipping_address": true
},
"pre_populated_data": {
"buyer_address": {
"address_line_1": "1455 MARKET ST #600",
"country": "US",
"administrative_district_level_1": "CA",
"locality": "San Jose",
"postal_code": "94103"
}
}
}'
A checkout page always includes a CONTACT section showing empty UI fields for the buyer to provide an email address and phone number. You can prepopulate these fields by adding the pre_populated_data
field in a CreatePaymentLink
request as shown. The request specifies an ad hoc item name and price to create a quick pay checkout and the optional pre_populated_data
field.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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"
}
}'
After receiving the request, Square creates an order, creates a checkout page, and returns a response. An example response is shown:
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
{
"payment_link": {
"id": "FV5LCO32HYNIRWLS",
"version": 1,
"order_id": "sCE4bdUkTU2OwIi0FsiYtMkmyWfZY",
"pre_populated_data": {
"buyer_email": "[email protected]",
"buyer_phone_number": "+14155551212"
},
"url": "https://sandbox.square.link/u/qD2HQsln",
"created_at": "2022-03-18T20:37:40Z"
},
"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"
}
}
]
}
}
When the buyer opens the checkout page, their email address and phone number are prepopulated. The buyer has the option to update the information. After the buyer pays, the email address and phone number are added to the order fulfillment (recipient
field).
Applications can include checkout_options
in a CreatePaymentLink
request to specify optional checkout page configurations. This includes enabling the buyer to add a tip, providing a shipping address, provide support email for buyer to contact the merchant, and adding up to two additional custom fields. An example request is shown:
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
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": "{LOCATON_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,
"merchant_support_email": "sup[email protected]",
"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
131
{
"payment_link": {
"id": "MVDBLSCHZP5ZUZOB",
"version": 1,
"order_id": "YggCup2fBKScqYhpIglzWMpJxyaZY",
"checkout_options": {
"allow_tipping": true,
"merchant_support_email": "[email protected]",
"custom_fields": [
{
"title": "Special Instructions",
"uid": "QPEENYORWCHZOUL4GO3EVNKL"
},
{
"title": "Would you like to be on mailing list",
"uid": "MWVZ74M34AT4NA4HK7LTB25L"
}
],
"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/d1Nflwbe",
"created_at": "2022-03-18T23:42:11Z"
},
"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"
}
}
]
}
}
You can also include a shipping fee and an application fee as a checkout option.
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
curl https://connect.squareupsandbox.com/v2/online-checkout/one-time-links \
-X POST \
-H 'Square-Version: 2022-03-16' \
-H 'Authorization: Bearer EAAAGfIQX8uWKWagu7294hoBzTZCr2Ca6L_WVL439T_lt0vKpGQvfdJb3k3WX_gr' \
-H 'Content-Type: application/json' \
-d '{
"idempotency_key": "{{idempotency_key}}",
"quick_pay": {
"name": "Gift box",
"price_money": {
"amount": 2000,
"currency": "USD"
},
"location_id": "{{location_id}}"
},
"checkout_options": {
"merchant_support_email": "[email protected]",
"ask_for_shipping_address": true,
"app_fee_money": {
"amount": 100,
"currency": "USD"
},
"shipping_fee": {
"name": "Shipping",
"charge": {
"amount": 499,
"currency": "USD"
}
}
},
"pre_populated_data": {
"buyer_email": "[email protected]"
},
"payment_note": "This is a payment note."
}
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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
{
"payment_link": {
"id": "PKGHMQUG4Z4XA7WU",
"version": 1,
"order_id": "{{order_id}}",
"checkout_options": {
"merchant_support_email": "[email protected]",
"ask_for_shipping_address": true,
"app_fee_money": {
"amount": 100,
"currency": "USD"
},
"shipping_fee": {
"name": "Shipping",
"charge": {
"amount": 499,
"currency": "USD"
}
}
},
"pre_populated_data": {
"buyer_email": "[email protected]"
},
"url": "https://square.link/u/NezpSrr534233",
"created_at": "2022-08-01T18:58:07Z",
"payment_note": "This is a payment note."
},
"related_resources": {
"orders": [
{
"id": "{{order_id}}",
"location_id": "{{location_id}}",
"source": {
"name": "My Payment Application"
},
"line_items": [
{
"uid": "HeKqE38KgTuF8cfQ36GxQC",
"name": "Gift box",
"quantity": "1",
"item_type": "ITEM",
"base_price_money": {
"amount": 2000,
"currency": "USD"
},
"variation_total_price_money": {
"amount": 2000,
"currency": "USD"
},
"gross_sales_money": {
"amount": 2000,
"currency": "USD"
},
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 2000,
"currency": "USD"
}
}
],
"service_charges": [
{
"uid": "YnyOWYvrKbyEip2AurRc6",
"name": "Shipping",
"amount_money": {
"amount": 499,
"currency": "USD"
},
"applied_money": {
"amount": 499,
"currency": "USD"
},
"total_money": {
"amount": 499,
"currency": "USD"
},
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"calculation_phase": "SUBTOTAL_PHASE",
"taxable": false,
"type": "CUSTOM"
}
],
"fulfillments": [
{
"uid": "AaUb3nFXzKh8ce3k6Rj1XB",
"type": "SHIPMENT",
"state": "PROPOSED",
"shipment_details": {
"recipient": {
"display_name": " ",
"email_address": "[email protected]"
}
}
}
],
"net_amounts": {
"total_money": {
"amount": 2499,
"currency": "USD"
},
"tax_money": {
"amount": 0,
"currency": "USD"
},
"discount_money": {
"amount": 0,
"currency": "USD"
},
"tip_money": {
"amount": 0,
"currency": "USD"
},
"service_charge_money": {
"amount": 499,
"currency": "USD"
}
},
"created_at": "2022-08-01T18:58:06.745Z",
"updated_at": "2022-08-01T18:58:06.745Z",
"state": "DRAFT",
"version": 1,
"total_money": {
"amount": 2499,
"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": 499,
"currency": "USD"
},
"net_amount_due_money": {
"amount": 2499,
"currency": "USD"
}
}
]
}
}
A checkout page always includes a COUPON
section showing an empty UI field for the buyer to provide a Square Marketing Coupon. You can show or hide the COUPON
section using the enable_coupon
field as a checkout option.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
curl https://connect.squareupsandbox.com/v2/online-checkout/payment-links \
-X POST \
-H 'Square-Version: 2022-03-16' \
-H 'Authorization: Bearer EAAAGfIQX8uWKWagu7294hoBzTZCr2Ca6L_WVL439T_lt0vKpGQvfdJb3k3WX_gr' \
-H 'Content-Type: application/json' \
-d '{
"idempotency_key": "{{idempotency_key}}",
"quick_pay": {
"name": "Auto Detailing",
"price_money": {
"amount": 12500,
"currency": "USD"
},
"location_id": "{{location_id}}"
},
"checkout_options": {
"enable_coupon": false
}
}
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
{
"payment_link": {
"id": "PKVT6XGJZXYUP3N554Z",
"version": 1,
"order_id": "{{order_id}}",
"checkout_options": {
"enable_coupon": false
},
"url": "https://square.link/u/NezpSrr534233",
"long_url": "https://checkout.square.site/merchant/ID/order/{order_id}",
},
"created_at": "2023-03-17T23:58:01Z",
"updated_at": "2022-08-01T18:58:06.745Z",
"state": "DRAFT",
"version": 1,
"total_money": {
"amount": 2499,
"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"
},
"net_amount_due_money": {
"amount": 12500,
"currency": "USD"
}
}
]
}
}
If the seller has enabled Square Loyalty, the checkout page includes a REWARDS
section that allows the buyer to sign up for a Loyalty program, accrue points, or redeem rewards. You can show or hide the REWARDS
section using the enable_loyalty
field as a checkout option.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
curl https://connect.squareupsandbox.com/v2/online-checkout/payment-links \
-X POST \
-H 'Square-Version: 2022-03-16' \
-H 'Authorization: Bearer EAAAGfIQX8uWKWagu7294hoBzTZCr2Ca6L_WVL439T_lt0vKpGQvfdJb3k3WX_gr' \
-H 'Content-Type: application/json' \
-d '{
"idempotency_key": "{{idempotency_key}}",
"quick_pay": {
"name": "Auto Detailing",
"price_money": {
"amount": 12500,
"currency": "USD"
},
"location_id": "{{location_id}}"
},
"checkout_options": {
"enable_loyalty": false
}
}
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
{
"payment_link": {
"id": "PKVT6XGJZXYUP3N554Z",
"version": 1,
"order_id": "{{order_id}}",
"checkout_options": {
"enable_loyalty": false
},
"url": "https://square.link/u/NezpSrr534233",
"long_url": "https://checkout.square.site/merchant/ID/order/{order_id}",
},
"created_at": "2023-03-17T23:58:01Z",
"updated_at": "2022-08-01T18:58:06.745Z",
"state": "DRAFT",
"version": 1,
"total_money": {
"amount": 2499,
"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"
},
"net_amount_due_money": {
"amount": 12500,
"currency": "USD"
}
}
]
}
}
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.