Create a session

This endpoint creates a session in our system, and it returns the URL that you should redirect the user to. You can use a session to create an order, tokenize a customer, or both.

We suggest you provide as much optional information about the user as you have available, since this will speed up our checkout process and increase conversion.

If you submit an order with a session, then Sezzle is able to handle the entire checkout process after an order has been provided. However, if your flow requires that the user confirm their checkout on your site after being approved by Sezzle, you may set the intent parameter to AUTH with the session request. In this flow, Sezzle will not complete the transaction unless you make a capture request. Capture requests can be made to capture all or part of the original order amount. You must send the capture request before the authorization expires. By default, authorizations expire within in 30 minutes, but the expiration period for new authorizations may be extended up to 7 days in your merchant dashboard.

If you choose to tokenize a customer, then the customer will have the option to agree to allow you to process future transactions on their behalf. This gives you the ability to preapprove and create orders on behalf of the customer.

Endpoint

POST https://gateway.sezzle.com/v2/session

Properties

Session Object

A valid session object contains at a minimum an Order object or a Customer object with tokenize set to true.

Parameter	Required	Type	Description
cancel_url	true	object	The HTTP request information used to redirect the customer in the case of a cancellation
complete_url	true	object	The HTTP request information used to redirect the customer upon completion of the session
customer	false*	object	The customer for this session
order	false*	object	The order for this session

* See the object specifications for special requirements.

URL Object

This is used for both the cancel and complete URL objects

Parameter	Required	Type	Description
href	true	string	The URL used when redirecting a customer
method	false	string	The HTTP request method used when redirecting a customer. Currently only the GET method is supported. If omitted, will default to GET.

Customer object

Shipping Address

Note: Merchants enrolled in Sezzle's Long Term Lending program (as well as general integrations) must send a Customer object that includes, at a minimum, a complete and valid shipping_address object. Post office box (i.e., P. O. Box) addresses are not accepted for this purpose. For more details, please contact your account manager.

Parameter	Required	Type	Description
tokenize	false	boolean	Determines whether to tokenize customer. If omitted, will default to false.
email	false	string	The customer's email address
first_name	false	string	The customer's first name
last_name	false	string	The customer's last name
phone	false	string	The customer's phone number
dob	false	string	The customer's date of birth in YYYY-MM-DD format (parameter is input only)
billing_address	false	object	The customer's billing address
shipping_address	false	object	The customer's shipping address.

Address Object

This format is used for both billing_address and shipping_address in the Customer object.

Parameter	Required	Type	Description
name	false	string	The name on the address
street	false	string	The street and number of the address
street2	false	string	The apt or unit
city	false	string	The city
state	false	string	The 2 character state code
postal_code	false	string	The postal delivery code
country_code	false	string	The 2 character country code
phone_number	false	string	The phone number at the delivery location

Order Object

Parameter	Required	Type	Description
intent	true	string	Accepted values are "AUTH" or "CAPTURE". If your checkout flow requires the user to confirm their checkout on your site after being approved by Sezzle, use "AUTH" as your intent. If you prefer the checkout be captured immediately, use "CAPTURE".
reference_id	true	string	Your reference ID for this order (must contain only alphanumeric characters, dashes (-), and underscores (_))
description	true	string	Your description for this order
order_amount	true	object	A Price object containing the amount in cents of the order, which must be at least `100` which is $1.00. Please note your merchant configuration might have a higher minimum. All fields of the Price object are required.
requires_shipping_info	false	boolean	Flag to indicate if you would like us to collect shipping information for this checkout from the customer. If omitted, defaults to false.
checkout_financing_options	false	array	The financing options of the checkout. Only one option can be included.
items	false	object	The items being purchased
discounts	false	object	The discounts applied to this order. Must be included in total
metadata	false	object	Object for any custom data you want to submit with the checkout. You are not limited to the key-value pairs shown in the example, and you may use any key-value pairs you like
shipping_amount	false	object	The shipping fees applied to this order. Must be included in the total
tax_amount	false	object	The taxes applied to this order. Must be included in the total
checkout_expiration	false	string	The expiration for the order checkout in ISO 8601 date/time format
checkout_mode	false	string	The mode for the order checkout. Defaults to `redirect` if not provided. If `iframe` or `popup` is provided, then the cancel and complete URLs must include the origin of the parent window.
send_checkout_url	false	object	A Notification object for sending checkout URL to the customer
locale	false	string	Localizes the checkout. Accepted values are `en-US` (English, United States), `en-CA` (English, Canada) and `fr-CA` (French, Canada). Defaults to `en-US` if not provided.

Item Object

Item Storage

Note: Merchants who are in the Sports & Hobbies or Hunting & Fishing categories must define a category_path for each item in the order. Please talk with your account manager for further details.

Parameter	Required	Type	Description
name	false	string	The name of the item
sku	false	string	The sku identifier
quantity	false	int	The quantity purchased
price	false	object	The price object
brand	false	string	The products brand name as customers would recognize. Examples: Nike, Kelty, Brooks, Carhartt, Columbia
image_url	false	string	The fully qualified URL that shows the image
product_url	false	string	The fully qualified URL that links directly to the product being purchased
category_path	false	string	The category path where the product is located. Example: `Camping Gear & Supplies > Tents & Shelters`.
global_trade_item_number	false	string	The products Global Trade Item Number (GTIN). Common types include UPC, ISBN, EAN. Exclude dashes and spaces.
manufacturer_part_number	false	string	The products Manufacturer Part Number (MPN) which together with brand can uniquely identify a product.

Discount Object

Parameter	Required	Type	Description
name	false	string	The description of the discount
amount	false	object	A price object

Metadata Object

Use the metadata object for any additional information you would like to attach to the checkout. All values must be strings.

Parameter	Required	Type	Description
some_field_name	false	string	Custom metadata field
some_other_field_name	false	string	Custom metadata field

Shipping Amount Object

A price object

Tax Amount Object

A price object

Price Object

The price object is used for items, discounts, shipping amount, tax amount, and order amount.

Parameter	Required	Type	Description
amount_in_cents	false	int	The amount of the item in cents
currency	false	string	The 3 character currency code as defined by ISO 4217

Notification Object

A valid notification object contains at a minimum a phone or an email.

Parameter	Required	Type	Description
to_sms_phone	false	string	The SMS phone number of the notification
to_email	false	string	The email address of the notification
language	false	string	The 2-character ISO 639 langauge code of the notification. Acceptable values are "en" and "fr-CA". Will default to English if not provided.

Tokenize Object

This is included in the response when starting a customer tokenization session.

Parameter	Required	Type	Description
token	false	string	This token represents the merchant request to tokenize a customer. This token can only be used one time. Once a user accepts/denies tokenization, this token and its approval URL will be obsolete.
expiration	false	string	The expiration of the request token in ISO 8601 date/time format.
approval_url	false	string	The URL for the user to accept tokenization. This URL does not create an order, it is only used for tokenizing a customer.

Examples

Session Request

{
  "cancel_url": {
    "href": "https://example.com/cart",
    "method": "GET"
  },
  "complete_url": {
    "href": "https://example.com/ord_12345/complete",
    "method": "GET"
  },
  "customer": {
    "email": "john.doe@sezzle.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "5555045294",
    "dob": "1990-02-25",
    "billing_address": {
      "name": "John Doe",
      "street": "123 W Lake St",
      "street2": "Unit 104",
      "city": "Minneapolis",
      "state": "MN",
      "postal_code": "55408",
      "country_code": "US",
      "phone_number": "5555045294"
    },
    "shipping_address": {
      "name": "John Doe",
      "street": "123 W Lake St",
      "street2": "Unit 104",
      "city": "Minneapolis",
      "state": "MN",
      "postal_code": "55408",
      "country_code": "US",
      "phone_number": "5555045294"
    }
  },
  "order": {
    "intent": "CAPTURE",
    "reference_id": "ord_12345",
    "description": "sezzle-store - #12749253509255",
    "items": [
      {
        "name": "widget",
        "sku": "sku123456",
        "quantity": 1,
        "price": {
          "amount_in_cents": 1000,
          "currency": "USD"
        }
      }
    ],
    "discounts": [
      {
        "name": "20% off",
        "amount": {
          "amount_in_cents": 1000,
          "currency": "USD"
        }
      }
    ],
    "metadata": {
      "location_id": "123",
      "store_name": "Downtown Minneapolis",
      "store_manager": "Jane Doe"
    },
    "shipping_amount": {
      "amount_in_cents": 1000,
      "currency": "USD"
    },
    "tax_amount": {
      "amount_in_cents": 1000,
      "currency": "USD"
    },
    "order_amount": {
      "amount_in_cents": 10000,
      "currency": "USD"
    }
  }
}

Session Response

{
  "uuid": "fadbc642-05a4-4e38-9e74-80e325623af9",
  "links": [
    {
      "href": "https://gateway.sezzle.com/v2/session/fadbc642-05a4-4e38-9e74-80e325623af9",
      "method": "GET",
      "rel": "self"
    }
  ],
  "order": {
    "uuid": "12a34bc5-6de7-890f-g123-4hi1238jk902",
    "checkout_url": "https://checkout.sezzle.com/?id=12a34bc5-6de7-890f-g123-4hi1238jk902",
    "intent": "CAPTURE",
    "links": [
      {
        "href": "https://gateway.sezzle.com/v2/order/12a34bc5-6de7-890f-g123-4hi1238jk902",
        "method": "GET",
        "rel": "self"
      },
      {
        "href": "https://gateway.sezzle.com/v2/order/12a34bc5-6de7-890f-g123-4hi1238jk902",
        "method": "PATCH",
        "rel": "self"
      },
      {
        "href": "https://gateway.sezzle.com/v2/order/12a34bc5-6de7-890f-g123-4hi1238jk902/release",
        "method": "POST",
        "rel": "release"
      },
      {
        "href": "https://gateway.sezzle.com/v2/order/12a34bc5-6de7-890f-g123-4hi1238jk902/capture",
        "method": "POST",
        "rel": "capture"
      },
      {
        "href": "https://gateway.sezzle.com/v2/order/12a34bc5-6de7-890f-g123-4hi1238jk902/refund",
        "method": "POST",
        "rel": "refund"
      }
    ]
  }
}

Multi-Purpose Session

It is possible to create an order and tokenize a customer in a single session by providing an order object and setting customer tokenize to true. In this instance, the response will include both order and tokenize objects and the user will be prompted to accept tokenization during checkout.

Endpoint​

Properties​

Session Object​

URL Object​

Customer object​

Address Object​

Order Object​

Item Object​

Discount Object​

Metadata Object​

Shipping Amount Object​

Tax Amount Object​

Price Object​

Notification Object​

Tokenize Object​

Examples​

Session Request​

Session Response​