Learn how to specify optional checkout configurations.
Checkout API

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).

Prepopulate the shipping address Permalink Get a link to this section

By default, the checkout page does not 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.

Create Payment Link
  • 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-06-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:

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 from DRAFT to OPEN.

  • 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:

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
curl https://connect.squareupsandbox.com/v2/online-checkout/payment-links \
  -X POST \
  -H 'Square-Version: 2022-06-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"
      }
    }
  }'

Prepopulate the email address and phone number Permalink Get a link to this section

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.

Create Payment Link
  • 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: 2022-06-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": "buyer@email.com",
      "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:

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).

Specify checkout options Permalink Get a link to this section

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:

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
  • 40
curl https://connect.squareupsandbox.com/v2/online-checkout/payment-links \
  -X POST \
  -H 'Square-Version: 2022-06-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": "buyer@email.com",
      "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": "support@email.com",
      "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
{
  "payment_link": {
    "id": "MVDBLSCHZP5ZUZOB",
    "version": 1,
    "order_id": "YggCup2fBKScqYhpIglzWMpJxyaZY",
    "checkout_options": {
      "allow_tipping": true,
      "merchant_support_email": "support@email.com"
      "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": "buyer@email.com",
      "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 topics Permalink Get a link to this section

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