Create checkout
Links a checkoutId
to a checkout_page_url
that customers are
directed to in order to provide their payment information using a
payment processing workflow hosted on connect.squareup.com.
NOTE: The Checkout API has been updated with new features. For more information, see Checkout API highlights. We recommend that you use the new CreatePaymentLink endpoint in place of this previously released endpoint.
Name | Description |
---|---|
location_
Required
|
The ID of the business location to associate the checkout with. |
Name | Description |
---|---|
idempotency_
Required
|
A unique string that identifies this checkout among others you have created. It can be any valid string but must be unique for every order sent to Square Checkout for a given location ID. The idempotency key is used to avoid processing the same order more than once. If you are unsure whether a particular checkout was created successfully, you can attempt it again with the same idempotency key and all the same other parameters without worrying about creating duplicates. You should use a random number/string generator native to the language you are working in to generate strings for your idempotency keys. For more information, see Idempotency. |
order
Required
|
The order including line items to be checked out. |
ask_
|
If Default: |
merchant_
|
The email address to display on the Square Checkout confirmation page and confirmation email that the buyer can use to contact the seller. If this value is not set, the confirmation page and email display the primary email address associated with the seller's Square account. Default: none; only exists if explicitly set. |
pre_
|
If provided, the buyer's email is prepopulated on the checkout page as an editable text field. Default: none; only exists if explicitly set. |
pre_
|
If provided, the buyer's shipping information is prepopulated on the checkout page as editable text fields. Default: none; only exists if explicitly set. |
redirect_
|
The URL to redirect to after the checkout is completed with
If you do not provide a redirect URL, Square Checkout displays an order confirmation page on your behalf; however, it is strongly recommended that you provide a redirect URL so you can verify the transaction results and finalize the order through your existing/normal confirmation workflow. Default: none; only exists if explicitly set. |
additional_
|
The basic primitive of a multi-party transaction. The value is optional. The transaction facilitated by you can be split from here. If you provide this value, the This field requires This field is currently not supported in the Square Sandbox. |
note
|
An optional note to associate with the This value cannot exceed 60 characters. |
Response Fields
Name | Description |
---|---|
checkout
|
The newly created |
errors
|
Any errors that occurred during the request. |
Examples
- cURL
- Ruby
- Python
- C#
- Java
- PHP
- Node.js
curl https://connect.squareup.com/v2/locations/location_id0/checkouts \
-X POST \
-H 'Square-Version: 2022-05-12' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"idempotency_key": "86ae1696-b1e3-4328-af6d-f1e04d947ad6",
"redirect_url": "https://merchant.website.com/order-confirm",
"order": {
"idempotency_key": "12ae1696-z1e3-4328-af6d-f1e04d947gd4",
"order": {
"location_id": "location_id",
"customer_id": "customer_id",
"reference_id": "reference_id",
"line_items": [
{
"name": "Printed T Shirt",
"quantity": "2",
"base_price_money": {
"amount": 1500,
"currency": "USD"
},
"applied_discounts": [
{
"discount_uid": "56ae1696-z1e3-9328-af6d-f1e04d947gd4"
}
],
"applied_taxes": [
{
"tax_uid": "38ze1696-z1e3-5628-af6d-f1e04d947fg3"
}
]
},
{
"name": "Slim Jeans",
"quantity": "1",
"base_price_money": {
"amount": 2500,
"currency": "USD"
}
},
{
"name": "Woven Sweater",
"quantity": "3",
"base_price_money": {
"amount": 3500,
"currency": "USD"
}
}
],
"taxes": [
{
"uid": "38ze1696-z1e3-5628-af6d-f1e04d947fg3",
"type": "INCLUSIVE",
"percentage": "7.75",
"scope": "LINE_ITEM"
}
],
"discounts": [
{
"uid": "56ae1696-z1e3-9328-af6d-f1e04d947gd4",
"type": "FIXED_AMOUNT",
"scope": "LINE_ITEM",
"amount_money": {
"amount": 100,
"currency": "USD"
}
}
]
}
},
"additional_recipients": [
{
"location_id": "057P5VYJ4A5X1",
"description": "Application fees",
"amount_money": {
"amount": 60,
"currency": "USD"
}
}
],
"ask_for_shipping_address": true,
"merchant_support_email": "merchant+support@website.com",
"pre_populate_buyer_email": "example@email.com",
"pre_populate_shipping_address": {
"address_line_1": "1455 Market St.",
"address_line_2": "Suite 600",
"locality": "San Francisco",
"administrative_district_level_1": "CA",
"postal_code": "94103",
"country": "US",
"first_name": "Jane",
"last_name": "Doe"
}
}'
{
"checkout": {
"id": "CAISEHGimXh-C3RIT4og1a6u1qw",
"checkout_page_url": "https://connect.squareup.com/v2/checkout?c=CAISEHGimXh-C3RIT4og1a6u1qw&l=CYTKRM7R7JMV8",
"ask_for_shipping_address": true,
"merchant_support_email": "merchant+support@website.com",
"pre_populate_buyer_email": "example@email.com",
"pre_populate_shipping_address": {
"address_line_1": "1455 Market St.",
"address_line_2": "Suite 600",
"locality": "San Francisco",
"administrative_district_level_1": "CA",
"postal_code": "94103",
"country": "US",
"first_name": "Jane",
"last_name": "Doe"
},
"redirect_url": "https://merchant.website.com/order-confirm",
"order": {
"location_id": "location_id",
"customer_id": "customer_id",
"reference_id": "reference_id",
"line_items": [
{
"name": "Printed T Shirt",
"quantity": "2",
"applied_taxes": [
{
"tax_uid": "38ze1696-z1e3-5628-af6d-f1e04d947fg3",
"applied_money": {
"amount": 103,
"currency": "USD"
}
}
],
"applied_discounts": [
{
"discount_uid": "56ae1696-z1e3-9328-af6d-f1e04d947gd4",
"applied_money": {
"amount": 100,
"currency": "USD"
}
}
],
"base_price_money": {
"amount": 1500,
"currency": "USD"
},
"total_tax_money": {
"amount": 103,
"currency": "USD"
},
"total_discount_money": {
"amount": 100,
"currency": "USD"
},
"total_money": {
"amount": 1503,
"currency": "USD"
}
},
{
"name": "Slim Jeans",
"quantity": "1",
"base_price_money": {
"amount": 2500,
"currency": "USD"
},
"total_money": {
"amount": 2500,
"currency": "USD"
}
},
{
"name": "Woven Sweater",
"quantity": "3",
"base_price_money": {
"amount": 3500,
"currency": "USD"
},
"total_money": {
"amount": 10500,
"currency": "USD"
}
}
],
"taxes": [
{
"uid": "38ze1696-z1e3-5628-af6d-f1e04d947fg3",
"type": "INCLUSIVE",
"percentage": "7.75",
"scope": "LINE_ITEM"
}
],
"discounts": [
{
"uid": "56ae1696-z1e3-9328-af6d-f1e04d947gd4",
"type": "FIXED_AMOUNT",
"scope": "LINE_ITEM",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"applied_money": {
"amount": 100,
"currency": "USD"
}
}
],
"total_money": {
"amount": 14503,
"currency": "USD"
},
"total_tax_money": {
"amount": 103,
"currency": "USD"
},
"total_discount_money": {
"amount": 100,
"currency": "USD"
}
},
"created_at": "2017-06-16T22:25:35Z",
"version": 1,
"additional_recipients": [
{
"location_id": "057P5VYJ4A5X1",
"description": "Application fees",
"amount_money": {
"amount": 60,
"currency": "USD"
}
}
]
}
}
Error Descriptions
400 Bad request |
AMOUNT_ The requested payment amount is too high for the provided payment source. |
> |
403 Forbidden |
CARD_ The location provided in the API call is not enabled for credit card processing. |
> |
{
"errors": [
{
"code": "AMOUNT_TOO_HIGH",
"category": "INVALID_REQUEST_ERROR"
}
]
}