Learn how to migrate an application from using the CreateCheckout endpoint to using the CreatePaymentLink endpoint.
Checkout API Migration

Migrate from CreateCheckout to CreatePaymentLink

Learn how to migrate an application from using the CreateCheckout endpoint to using the CreatePaymentLink endpoint.

The CreatePaymentLink endpoint provides all the functionality of the CreateCheckout endpoint and adds the following checkout options:

  • Shipping fees. You can add a shipping fee. The buyer sees the shipping fees during checkout on their order confirmation pages and receipts.

  • Application fee money. You can add an application fee. This amount is deposited to the Square developer account.

  • Custom fields. You can add up to two custom form fields to collect more information from buyers during checkout.

  • Accepted payment methods. You can add support for payment methods such as credit cards, debit cards, Google Pay, Apple Pay, Afterpay, and Cash App.

  • Allow tipping. You can add support for tipping.

  • Subscription plans (recurring payments). You can specify a subscription plan ID in the checkout request and charge the buyer for recurring payments.

  • Deprecation: 2022-08-17

  • Retirement: 2023-04-02

If you need help migrating to Square APIs or need more time to complete your migration, contact Developer Support, join our Slack, or reach out to your Square Account Manager.

The CreatePaymentLink endpoint replaces the CreateCheckout endpoint in the Checkout API.

Deprecated Checkout API endpoint
Replacement Checkout API endpoint
CreateCheckoutCreatePaymentLink

With the exception of the additional_recipients field, all fields in the CreateCheckout endpoint are also available in the CreatePaymentLink endpoint. As a result, most code only needs to update the endpoint reference and field names to work properly.

The following sections provide mapping information about the path parameters, query parameters, and response fields.

The following table shows how the CreateCheckout path parameters map to the CreatePaymentLink endpoint:

CreateCheckout path parameterCreatePaymentLink path parameterNote
location_idN/Alocation_id is changed to a query parameter.

The following table shows how the CreateCheckout query parameters map to the CreatePaymentLink endpoint:

CreateCheckout query parameter
CreatePaymentLink query parameter
Note
idempotency_keyidempotency_key
N/AdescriptionAdd a description of the payment link. For more information, see description.
N/Aquick_payGenerate a quick pay checkout link. For more information, see QuickPay.
orderorder
N/Acheckout_optionsAdd optional fields to the resulting checkout page. For more information about all the available options, see CheckoutOptions.
N/Acheckout_options.accepted_payment_methodsAccept various methods for payment. For more information, see AcceptedPaymentMethods.
N/Acheckout_options.allow_tippingEnable tipping on the checkout page. For more information, see allow_tipping.
ask_for_shipping_addresscheckout_options.ask_for_shipping_addressSee ask_for_shipping_address.
N/Acheckout_options.custom_fieldsAdd custom fields to request information from the buyer. For more information, see CustomFields.
merchant_support_emailcheckout_options.merchant_support_emailSee merchant_support_email.
redirect_urlcheckout_options.redirect_urlSee redirect_url.
N/Acheckout_options.subscription_plan_idAllow the buyer to pay and subscribe. For more information, see Subscription Plan Checkout.
N/Acheckout_options.shipping_feeAdd a shipping fee to the checkout page. For more information, see Shipping Fee.
N/Acheckout_options.app_fee_moneyAdd an application fee to the checkout page. For more information, see app_fee_money.
N/Apre_populated_dataAdd fields to prepopulate in the resulting checkout page. For more information, see PrePopulatedData.
pre_populate_shipping_addresspre_populated_data.buyer_addressSee buyer_address.
pre_populate_buyer_emailpre_populated_data.buyer_emailSee buyer_email.
N/Apre_populated_data.buyer_phone_numberPrepopulate the payment form with the buyer phone number. For more information, see buyer_phone_number.
N/AsourceProvide the application that created the payment link. For more information, see source.
notepayment_noteSee payment_note.
additional_recipientsN/AThis field is no longer supported. For more information, see additional_recipients.

The CreateCheckout endpoint returns checkout information as a Checkout object in the response body, whereas the CreatePaymentLink endpoint returns a PaymentLink object.

CreateCheckout field
CreatePaymentLink field
Note
idid
N/AversionThe Square-assigned version number, which is incremented each time an update is made to the payment link. For more information, see version.
N/Acheckout_optionsThe checkout options configured for the payment link. For more information, see CheckoutOptions.
ask_for_shipping_addresscheckout_options.ask_for_shipping_addressSee ask_for_shipping_address.
merchant_support_emailcheckout_options.merchant_support_emailSee merchant_support_email.
redirect_urlcheckout_options.redirect_urlSee redirect_url.
N/Acheckout_options.accepted_payment_methodsSee accepted_payment_method.
N/Acheckout_options.allow_tippingSee allow_tipping.
N/Acheckout_options.app_fee_moneySee app_fee_money.
N/Acheckout_options.custom_fieldsSee CustomFields.
N/Acheckout_options.shipping_feeSee ShippingFee.
N/Acheckout_options.subscription_plan_idSee Subscription Plan Checkout.
created_atcreated_atSee created_at.
N/AdescriptionThe optional description of the payment_link object. For more information, see description.
N/Aorder_idThe ID of the order associated with the payment link. For more information, see order_id.
N/Apayment_noteThe optional note for the payment link. For more information, see payment_note.
N/Apre_populated_dataThe buyer data to prepopulate on the checkout page. For more information, see pre_populated_data.
pre_populate_buyer_emailpre_populated_data.buyer_emailSee buyer_email.
pre_populate_shipping_addresspre_populated_data.buyer_addressSee buyer_address.
N/Apre_populated_data.buyer_phone_numberThe buyer phone number to prepopulate in the payment form. For more information, see buyer_phone_number.
N/Aupdated_atThe timestamp when the payment link was last updated, in RFC 3339 format. For more information, see updated_at.
checkout_page_urlurlSee url.
N/Arelated_resourcesThe list of related objects. For more information, see Related Resources.
orderrelated_resources.ordersThe order to be checked out. For more information, see orders.
N/Arelated_resources.subscription_plansThe subscription plan that is associated with the payment link. For more information, see subscription_plans.
additional_recipientsN/A

CreateCheckout to CreatePaymentLink

The following example shows a request to create a Square-hosted checkout page with the CreateCheckout endpoint:

  • 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
curl https://connect.squareup.com/v2/locations/{{LOCATION_ID}}/checkouts \
  -X POST \
  -H 'Square-Version: 2022-08-17' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{{IDEMPOTENCY_KEY}}",
    "order": {
      "idempotency_key": "{{IDEMPOTENCY_KEY}}",
      "order": {
        "location_id": "{{LOCATION_ID}}",
        "line_items": [
          {
            "quantity": "1",
            "name": "Single Item",
            "base_price_money": {
              "amount": 100,
              "currency": "USD"
            }
          }
        ],
        "pricing_options": {}
      }
    },
    "ask_for_shipping_address": true,
    "merchant_support_email": "merchant@support.com",
    "note": "This is a payment note.",
    "pre_populate_buyer_email": "buyer_email@example.com",
    "redirect_url": "https://squareup.com/us/en"
  }'

The following shows the CreateCheckout 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
 {
  "checkout": {
    "id": "CBYSEJO6_Q5vm8j0tRiusFPHe3E",
    "checkout_page_url": "https://connect.square.com/v2/checkout?c=CBYSEJO6_Q5vm8j0tRiusFPHe3E&l=LNWF3144PE6KQ",
    "ask_for_shipping_address": true,
    "merchant_support_email": "merchant@support.com",
    "pre_populate_buyer_email": "buyer_email@example.com",
    "redirect_url": "https://squareup.com/us/en",
    "order": {
      "id": "HY1wWSPqmDIQATK29APdwkqRxpfZY",
      "location_id": "{{LOCATION_ID}}",
      "source": {
        "name": "Sandbox for sq0ids-KRz107oXYBYGc1SodQIvvg"
      },
      "line_items": [
        {
          "uid": "2z3V4IveGSGerbLHqD92bC",
          "name": "Single Item",
          "quantity": "1",
          "item_type": "ITEM",
          "base_price_money": {
            "amount": 100,
            "currency": "USD"
          },
          "variation_total_price_money": {
            "amount": 100,
            "currency": "USD"
          },
          "gross_sales_money": {
            "amount": 100,
            "currency": "USD"
          },
          "total_tax_money": {
            "amount": 0,
            "currency": "USD"
          },
          "total_discount_money": {
            "amount": 0,
            "currency": "USD"
          },
          "total_money": {
            "amount": 100,
            "currency": "USD"
          },
          "total_service_charge_money": {
            "amount": 0,
            "currency": "USD"
          }
        }
      ],
      "net_amounts": {
        "total_money": {
          "amount": 100,
          "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-07-18T21:19:36.138Z",
      "updated_at": "2022-07-18T21:19:36.138Z",
      "state": "OPEN",
      "version": 1,
      "total_money": {
        "amount": 100,
        "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"
      },
      "pricing_options": {},
      "net_amount_due_money": {
        "amount": 100,
        "currency": "USD"
      },
      "processing_modes": {
        "creation_processing_mode": "ONLINE"
      }
    },
    "created_at": "2022-07-18T21:19:36Z"
  }
}

Example CreatePaymentLink request

The following example shows a request to create a Square-hosted checkout page with the CreatePaymentLink endpoint:

The following shows the CreatePaymentLink 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
 {
  "payment_link": {
    "id": "OOPRDFFPREYYW2WE",
    "version": 1,
    "order_id": "{{ORDER_ID}}",
    "checkout_options": {
      "redirect_url": "https://squareup.com/us/en",
      "merchant_support_email": "merchant@support.com",
      "ask_for_shipping_address": true
    },
    "pre_populated_data": {
      "buyer_email": "buyer_email@support.com"
    },
    "url": "https://staging.square.link/u/zVN4FvYF",
    "created_at": "2022-07-18T21:36:27Z",
    "payment_note": "This is a payment note."
  },
  "related_resources": {
        "orders": [
            {
                "id": "C53atpKqBTRcpkAahnujKDEwbZTZY",
                "location_id": "{{LOCATION_ID}}",
                "source": {
                    "name": "{{APPLICATION_NAME}}"
                },
                "line_items": [
                    {
                        "uid": "1cGNNk0QQCvwjKs0tKGICC",
                        "name": "Single Item",
                        "quantity": "1",
                        "item_type": "ITEM",
                        "base_price_money": {
                            "amount": 100,
                            "currency": "USD"
                        },
                        "variation_total_price_money": {
                            "amount": 100,
                            "currency": "USD"
                        },
                        "gross_sales_money": {
                            "amount": 100,
                            "currency": "USD"
                        },
                        "total_tax_money": {
                            "amount": 0,
                            "currency": "USD"
                        },
                        "total_discount_money": {
                            "amount": 0,
                            "currency": "USD"
                        },
                        "total_money": {
                            "amount": 100,
                            "currency": "USD"
                        }
                    }
                ],
                "fulfillments": [
                    {
                        "uid": "5ndxErZdfk6vsQyU3Dpsq",
                        "type": "SHIPMENT",
                        "state": "PROPOSED",
                        "shipment_details": {
                            "recipient": {
                                "display_name": " ",
                                "email_address": "buyer_email@support.com"
                            }
                        }
                    }
                ],
                "net_amounts": {
                    "total_money": {
                        "amount": 100,
                        "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"
                    }
                },
                "metadata": {
                    "square:ask_for_shipping": "true",
                    "square:merchant_support_email": "merchant@support.com",
                    "square:redirect_url": "https://squareup.com/us/en"
                },
                "created_at": "2022-07-25T17:56:39.973Z",
                "updated_at": "2022-07-25T17:56:39.973Z",
                "state": "DRAFT",
                "version": 1,
                "total_money": {
                    "amount": 100,
                    "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": 100,
                    "currency": "USD"
                }
            }
        ]
    }
}

The following example shows a CreatePaymentLink request with an Order object:

  • 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
curl https://connect.squareup.com/v2/online-checkout/payment-links \
  -X POST \
  -H 'Square-Version: 2022-08-17' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
  "idempotency_key": "{{idempotency_key}}",
  "order": {
    "location_id": "9508d057-2c57-4632-9016-356968c242c3",
    "line_items": [
      {
        "name": "Single Item",
        "quantity": "1",
        "item_type": "ITEM",
        "base_price_money": {
          "amount": 100,
          "currency": "USD"
        }
      }
    ]
  },
  "payment_note": "This is a payment note.",
  "checkout_options": {
    "ask_for_shipping_address": true,
    "merchant_support_email": "merchant@support.com",
    "redirect_url": "https://squareup.com/us/en"
  },
  "pre_populated_data": {
    "buyer_email": "buyer_email@support.com"
  }
}'

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
{
    "payment_link": {
        "id": "YLVOYD7KGY3MVTOP",
        "version": 1,
        "order_id": "{{ORDER_ID}}",
        "checkout_options": {
            "redirect_url": "https://squareup.com/us/en",
            "merchant_support_email": "merchant@support.com",
            "ask_for_shipping_address": true
        },
        "pre_populated_data": {
            "buyer_email": "buyer_email@support.com"
        },
        "url": "https://staging.square.link/u/KKwwg4PTUFUE",
        "created_at": "2022-08-16T21:52:52Z",
        "payment_note": "This is a payment note."
    },
    "related_resources": {
        "orders": [
            {
                "id": "{{ORDER_ID}}",
                "location_id": "{{LOCATION_ID}}",
                "source": {
                    "name": "My Payment Integration Application"
                },
                "line_items": [
                    {
                        "uid": "Mzh71AisCrWoZhTLRPNTR",
                        "name": "Single Item",
                        "quantity": "1",
                        "item_type": "ITEM",
                        "base_price_money": {
                            "amount": 100,
                            "currency": "USD"
                        },
                        "variation_total_price_money": {
                            "amount": 100,
                            "currency": "USD"
                        },
                        "gross_sales_money": {
                            "amount": 100,
                            "currency": "USD"
                        },
                        "total_tax_money": {
                            "amount": 0,
                            "currency": "USD"
                        },
                        "total_discount_money": {
                            "amount": 0,
                            "currency": "USD"
                        },
                        "total_money": {
                            "amount": 100,
                            "currency": "USD"
                        }
                    }
                ],
                "fulfillments": [
                    {
                        "uid": "gmBcYydLf49PgmNuRoUoGD",
                        "type": "SHIPMENT",
                        "state": "PROPOSED",
                        "shipment_details": {
                            "recipient": {
                                "display_name": " ",
                                "email_address": "buyer_email@support.com"
                            }
                        }
                    }
                ],
                "net_amounts": {
                    "total_money": {
                        "amount": 100,
                        "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-08-16T21:52:50.952Z",
                "updated_at": "2022-08-16T21:52:50.952Z",
                "state": "DRAFT",
                "version": 1,
                "total_money": {
                    "amount": 100,
                    "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": 100,
                    "currency": "USD"
                }
            }
        ]
    }
}

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