Migrate from CreateCheckout to CreatePaymentLink

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

Overview

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.

Link to section

Important dates

Deprecation: 2022-08-17
Retirement: TBD

Link to section

Get help

If you need help migrating to Square APIs or need more time to complete your migration, contact Developer Support, join our Discord community, or reach out to your Square account manager.

Link to section

Endpoints

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

Deprecated Checkout API endpoint	Replacement Checkout API endpoint
CreateCheckout	CreatePaymentLink

Link to section

Field mappings

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.

Link to section

Path parameter mappings

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

CreateCheckout path parameter	CreatePaymentLink path parameter	Note
`location_id`	N/A	`location_id` is changed to a query parameter.

Link to section

Query parameter mappings

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

CreateCheckout query parameter	CreatePaymentLink query parameter	Note
`idempotency_key`	`idempotency_key`
N/A	`description`	Add a description of the payment link. For more information, see description.
N/A	`quick_pay`	Generate a quick pay checkout link. For more information, see QuickPay.
`order`	`order`
N/A	`checkout_options`	Add optional fields to the resulting checkout page. For more information about all the available options, see CheckoutOptions.
N/A	`checkout_options.accepted_payment_methods`	Accept various methods for payment. For more information, see AcceptedPaymentMethods.
N/A	`checkout_options.allow_tipping`	Enable tipping on the checkout page. For more information, see allow_tipping.
`ask_for_shipping_address`	`checkout_options.ask_for_shipping_address`	See ask_for_shipping_address.
N/A	`checkout_options.custom_fields`	Add custom fields to request information from the buyer. For more information, see CustomFields.
`merchant_support_email`	`checkout_options.merchant_support_email`	See merchant_support_email.
`redirect_url`	`checkout_options.redirect_url`	See redirect_url.
N/A	`checkout_options.subscription_plan_id`	Allow the buyer to pay and subscribe. For more information, see Subscription Plan Checkout.
N/A	`checkout_options.shipping_fee`	Add a shipping fee to the checkout page. For more information, see Shipping Fee.
N/A	`checkout_options.app_fee_money`	Add an application fee to the checkout page. For more information, see app_fee_money.
N/A	`pre_populated_data`	Add fields to prepopulate in the resulting checkout page. For more information, see PrePopulatedData.
`pre_populate_shipping_address`	`pre_populated_data.buyer_address`	See buyer_address.
`pre_populate_buyer_email`	`pre_populated_data.buyer_email`	See buyer_email.
N/A	`pre_populated_data.buyer_phone_number`	Prepopulate the payment form with the buyer phone number. For more information, see buyer_phone_number.
N/A	`source`	Provide the application that created the payment link. For more information, see source.
`note`	`payment_note`	See payment_note.
`additional_recipients`	N/A	This field is no longer supported. For more information, see additional_recipients.

Link to section

Response field mappings

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
`id`	`id`
N/A	`version`	The Square-assigned version number, which is incremented each time an update is made to the payment link. For more information, see version.
N/A	`checkout_options`	The checkout options configured for the payment link. For more information, see CheckoutOptions.
`ask_for_shipping_address`	`checkout_options.ask_for_shipping_address`	See ask_for_shipping_address.
`merchant_support_email`	`checkout_options.merchant_support_email`	See merchant_support_email.
`redirect_url`	`checkout_options.redirect_url`	See redirect_url.
N/A	`checkout_options.accepted_payment_methods`	See accepted_payment_method.
N/A	`checkout_options.allow_tipping`	See allow_tipping.
N/A	`checkout_options.app_fee_money`	See app_fee_money.
N/A	`checkout_options.custom_fields`	See CustomFields.
N/A	`checkout_options.shipping_fee`	See ShippingFee.
N/A	`checkout_options.subscription_plan_id`	See Subscription Plan Checkout.
`created_at`	`created_at`	See created_at.
N/A	`description`	The optional description of the `payment_link` object. For more information, see description.
N/A	`order_id`	The ID of the order associated with the payment link. For more information, see order_id.
N/A	`payment_note`	The optional note for the payment link. For more information, see payment_note.
N/A	`pre_populated_data`	The buyer data to prepopulate on the checkout page. For more information, see pre_populated_data.
`pre_populate_buyer_email`	`pre_populated_data.buyer_email`	See buyer_email.
`pre_populate_shipping_address`	`pre_populated_data.buyer_address`	See buyer_address.
N/A	`pre_populated_data.buyer_phone_number`	The buyer phone number to prepopulate in the payment form. For more information, see buyer_phone_number.
N/A	`updated_at`	The timestamp when the payment link was last updated, in RFC 3339 format. For more information, see updated_at.
`checkout_page_url`	`url`	See url.
N/A	`related_resources`	The list of related objects. For more information, see Related Resources.
`order`	`related_resources.orders`	The order to be checked out. For more information, see orders.
N/A	`related_resources.subscription_plans`	The subscription plan that is associated with the payment link. For more information, see subscription_plans.
`additional_recipients`	N/A

Link to section

Migrate to the CreatePaymentLink endpoint

CreateCheckout to CreatePaymentLink

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

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": "[email protected]",
    "note": "This is a payment note.",
    "pre_populate_buyer_email": "[email protected]",
    "redirect_url": "https://squareup.com/us/en"
  }'

The following shows the CreateCheckout response:

 {
  "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": "[email protected]",
    "pre_populate_buyer_email": "[email protected]",
    "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:

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 '{
    "quick_pay": {
      "location_id": "{{LOCATION_ID}}",
      "name": "Single Item",
      "price_money": {
        "amount": 100,
        "currency": "USD"
      }
    },
    "payment_note": "This is a payment note.",
    "idempotency_key": "cffff407-073f-4f9d-af03-d040f99927b7",
    "checkout_options": {
      "ask_for_shipping_address": true,
      "merchant_support_email": "[email protected]",
      "redirect_url": "https://squareup.com/us/en"
    },
    "pre_populated_data": {
      "buyer_email": "[email protected]"
    }
  }'

The following shows the CreatePaymentLink response:

 {
  "payment_link": {
    "id": "OOPRDFFPREYYW2WE",
    "version": 1,
    "order_id": "{{ORDER_ID}}",
    "checkout_options": {
      "redirect_url": "https://squareup.com/us/en",
      "merchant_support_email": "[email protected]",
      "ask_for_shipping_address": true
    },
    "pre_populated_data": {
      "buyer_email": "[email protected]"
    },
    "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": "[email protected]"
                            }
                        }
                    }
                ],
                "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": "[email protected]",
                    "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:

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": "[email protected]",
    "redirect_url": "https://squareup.com/us/en"
  },
  "pre_populated_data": {
    "buyer_email": "[email protected]"
  }
}'

The following is an example response:

{
    "payment_link": {
        "id": "YLVOYD7KGY3MVTOP",
        "version": 1,
        "order_id": "{{ORDER_ID}}",
        "checkout_options": {
            "redirect_url": "https://squareup.com/us/en",
            "merchant_support_email": "[email protected]",
            "ask_for_shipping_address": true
        },
        "pre_populated_data": {
            "buyer_email": "[email protected]"
        },
        "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": "[email protected]"
                            }
                        }
                    }
                ],
                "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"
                }
            }
        ]
    }
}

Docs

Migrate from CreateCheckout to CreatePaymentLink

On this page

Overview

Important dates

Get help

Endpoints

Field mappings

Path parameter mappings

Query parameter mappings

Response field mappings

Migrate to the CreatePaymentLink endpoint

On this page