Skip to content

Latest commit

 

History

History
119 lines (110 loc) · 6.4 KB

create-checkout-request.md

File metadata and controls

119 lines (110 loc) · 6.4 KB
Raw

Create Checkout Request

Defines the parameters that can be included in the body of a request to the CreateCheckout endpoint.

Structure

CreateCheckoutRequest

Fields

Name Type Tags Description
idempotencyKey string 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.
Constraints: Minimum Length: 1, Maximum Length: 192
order CreateOrderRequest Required -
askForShippingAddress boolean | undefined Optional If true, Square Checkout collects shipping information on your behalf and stores
that information with the transaction information in the Square Seller Dashboard.

Default: false.
merchantSupportEmail string | undefined Optional 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.
Constraints: Maximum Length: 254
prePopulateBuyerEmail string | undefined Optional If provided, the buyer's email is prepopulated on the checkout page
as an editable text field.

Default: none; only exists if explicitly set.
Constraints: Maximum Length: 254
prePopulateShippingAddress Address | undefined Optional Represents a postal address in a country.
For more information, see Working with Addresses.
redirectUrl string | undefined Optional The URL to redirect to after the checkout is completed with checkoutId,
transactionId, and referenceId appended as URL parameters. For example,
if the provided redirect URL is http://www.example.com/order-complete, a
successful transaction redirects the customer to:

http://www.example.com/order-complete?checkoutId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx

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.
Constraints: Maximum Length: 800
additionalRecipients ChargeRequestAdditionalRecipient[] | undefined Optional 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 amount_money value in your additional_recipients field
cannot be more than 90% of the total_money calculated by Square for your order.
The location_id must be a valid seller location where the checkout is occurring.

This field requires PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission.

This field is currently not supported in the Square Sandbox.
note string | undefined Optional An optional note to associate with the checkout object.

This value cannot exceed 60 characters.
Constraints: Maximum Length: 60

Example (as JSON)

{
  "additional_recipients": [
    {
      "amount_money": {
        "amount": 60,
        "currency": "USD"
      },
      "description": "Application fees",
      "location_id": "057P5VYJ4A5X1"
    }
  ],
  "ask_for_shipping_address": true,
  "idempotency_key": "86ae1696-b1e3-4328-af6d-f1e04d947ad6",
  "merchant_support_email": "[email protected]",
  "order": {
    "idempotency_key": "12ae1696-z1e3-4328-af6d-f1e04d947gd4",
    "order": {
      "customer_id": "customer_id",
      "discounts": [
        {
          "amount_money": {
            "amount": 100,
            "currency": "USD"
          },
          "scope": "LINE_ITEM",
          "type": "FIXED_AMOUNT",
          "uid": "56ae1696-z1e3-9328-af6d-f1e04d947gd4"
        }
      ],
      "line_items": [
        {
          "applied_discounts": [
            {
              "discount_uid": "56ae1696-z1e3-9328-af6d-f1e04d947gd4"
            }
          ],
          "applied_taxes": [
            {
              "tax_uid": "38ze1696-z1e3-5628-af6d-f1e04d947fg3"
            }
          ],
          "base_price_money": {
            "amount": 1500,
            "currency": "USD"
          },
          "name": "Printed T Shirt",
          "quantity": "2"
        },
        {
          "base_price_money": {
            "amount": 2500,
            "currency": "USD"
          },
          "name": "Slim Jeans",
          "quantity": "1"
        },
        {
          "base_price_money": {
            "amount": 3500,
            "currency": "USD"
          },
          "name": "Woven Sweater",
          "quantity": "3"
        }
      ],
      "location_id": "location_id",
      "reference_id": "reference_id",
      "taxes": [
        {
          "percentage": "7.75",
          "scope": "LINE_ITEM",
          "type": "INCLUSIVE",
          "uid": "38ze1696-z1e3-5628-af6d-f1e04d947fg3"
        }
      ]
    }
  },
  "pre_populate_buyer_email": "[email protected]",
  "pre_populate_shipping_address": {
    "address_line_1": "1455 Market St.",
    "address_line_2": "Suite 600",
    "administrative_district_level_1": "CA",
    "country": "US",
    "first_name": "Jane",
    "last_name": "Doe",
    "locality": "San Francisco",
    "postal_code": "94103"
  },
  "redirect_url": "https://merchant.website.com/order-confirm"
}