Applies to: Checkout API
Learn how to add optional fields to a checkout page.
The checkout_options field in the CreatePaymentLink request allows you
to add optional fields to the resulting checkout page (see Checkout API). 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).
Use checkout_options.accepted_payment_methods to configure Apple Pay, Google Pay, Cash App Pay, Afterpay/Clearpay, and ACH bank transfers on a payment link. See AcceptedPaymentMethods for the available fields. Seller settings and payment method eligibility also apply.
ACH defaults on for eligible sellers without a saved preference and for new eligible one-time USD links when the seller accepts ACH. Omit bank_account to use the link default, or set it to false to turn off ACH for the link. Existing API-generated links keep their saved choices; set bank_account to true to add ACH to an existing link. The link option doesn't override a seller's saved opt-out.
The following request explicitly enables ACH for a new payment link. Replace {UNIQUE_KEY} with a unique idempotency key and {LOCATION_ID} with the seller's US location ID. Set bank_account to false to opt out instead.
If the seller isn't eligible, explicitly enabling ACH returns an error for checkout_options.accepted_payment_methods.bank_account.
When calling UpdatePaymentLink, retrieve the link's current version and full checkout_options, change the payment method, and send the full options object. The update deletes options that you omit. See Manage Checkout.
On the hosted checkout page, the buyer chooses bank transfer, connects their bank account through Plaid, and authorizes the payment. Square handles bank verification and payment submission. Your application doesn't need a Plaid account, a Web Payments SDK integration, or a separate CreatePayment call for this flow.
ACH payments are asynchronous and have Payment.source_type set to BANK_ACCOUNT. Track payment.created and payment.updated webhooks, or call GetPayment. Match Payment.order_id to the order and wait for Payment.status to be COMPLETED before fulfillment. PENDING means the transfer is processing; FAILED means it didn't complete. A checkout confirmation or redirect doesn't confirm payment completion. See ACH Bank Transfer Payment for processing times, refunds, and returns.
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.
The following is an example response:
{ "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
statefromDRAFTtoOPEN. - Updates
Order.fulfillments.shipment_detailsto 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:
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.
After receiving the request, Square creates an order, creates a checkout page, and returns a response. An example response is shown:
{ "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:
The following is an example response:
{ "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.
curl https://connect.squareupsandbox.com/v2/online-checkout/one-time-links \ -X POST \ -H 'Square-Version: 2022-03-16' \ -H 'Authorization: Bearer {ACCESS_TOKEN}' \ -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:
{ "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.
curl https://connect.squareupsandbox.com/v2/online-checkout/payment-links \ -X POST \ -H 'Square-Version: 2022-03-16' \ -H 'Authorization: Bearer {ACCESS_TOKEN}' \ -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:
{ "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}" }, "related_resources": { "orders": [ { "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.
curl https://connect.squareupsandbox.com/v2/online-checkout/payment-links \ -X POST \ -H 'Square-Version: 2022-03-16' \ -H 'Authorization: Bearer {ACCESS_TOKEN}' \ -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:
{ "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}" }, "related_resources": { "orders": [ { "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" } } ] } }