Skip to main content

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.

ParameterRequiredTypeDescription
cancel_urltrueobjectThe HTTP request information used to redirect the customer in the case of a cancellation
complete_urltrueobjectThe HTTP request information used to redirect the customer upon completion of the session
customerfalse*objectThe customer for this session
orderfalse*objectThe order for this session

* See the object specifications for special requirements.

URL Object

This is used for both the cancel and complete URL objects

ParameterRequiredTypeDescription
hreftruestringThe URL used when redirecting a customer
methodfalsestringThe 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.

ParameterRequiredTypeDescription
tokenizefalsebooleanDetermines whether to tokenize customer. If omitted, will default to false.
emailfalsestringThe customer's email address
first_namefalsestringThe customer's first name
last_namefalsestringThe customer's last name
phonefalsestringThe customer's phone number
dobfalsestringThe customer's date of birth in YYYY-MM-DD format (parameter is input only)
billing_addressfalseobjectThe customer's billing address
shipping_addressfalseobjectThe customer's shipping address.

Address Object

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

ParameterRequiredTypeDescription
namefalsestringThe name on the address
streetfalsestringThe street and number of the address
street2falsestringThe apt or unit
cityfalsestringThe city
statefalsestringThe 2 character state code
postal_codefalsestringThe postal delivery code
country_codefalsestringThe 2 character country code
phone_numberfalsestringThe phone number at the delivery location

Order Object

ParameterRequiredTypeDescription
intenttruestringAccepted 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_idtruestringYour reference ID for this order (must contain only alphanumeric characters, dashes (-), and underscores (_))
descriptiontruestringYour description for this order
order_amounttrueobjectA 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_infofalsebooleanFlag to indicate if you would like us to collect shipping information for this checkout from the customer. If omitted, defaults to false.
checkout_financing_optionsfalsearrayThe financing options of the checkout. Only one option can be included.
itemsfalseobjectThe items being purchased
discountsfalseobjectThe discounts applied to this order. Must be included in total
metadatafalseobjectObject 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_amountfalseobjectThe shipping fees applied to this order. Must be included in the total
tax_amountfalseobjectThe taxes applied to this order. Must be included in the total
checkout_expirationfalsestringThe expiration for the order checkout in ISO 8601 date/time format
checkout_modefalsestringThe 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_urlfalseobjectA Notification object for sending checkout URL to the customer
localefalsestringLocalizes 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.

ParameterRequiredTypeDescription
namefalsestringThe name of the item
skufalsestringThe sku identifier
quantityfalseintThe quantity purchased
pricefalseobjectThe price object
brandfalsestringThe products brand name as customers would recognize. Examples: Nike, Kelty, Brooks, Carhartt, Columbia
image_urlfalsestringThe fully qualified URL that shows the image
product_urlfalsestringThe fully qualified URL that links directly to the product being purchased
category_pathfalsestringThe category path where the product is located. Example: Camping Gear & Supplies > Tents & Shelters.
global_trade_item_numberfalsestringThe products Global Trade Item Number (GTIN). Common types include UPC, ISBN, EAN. Exclude dashes and spaces.
manufacturer_part_numberfalsestringThe products Manufacturer Part Number (MPN) which together with brand can uniquely identify a product.

Discount Object

ParameterRequiredTypeDescription
namefalsestringThe description of the discount
amountfalseobjectA 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.

ParameterRequiredTypeDescription
some_field_namefalsestringCustom metadata field
some_other_field_namefalsestringCustom 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.

ParameterRequiredTypeDescription
amount_in_centsfalseintThe amount of the item in cents
currencyfalsestringThe 3 character currency code as defined by ISO 4217

Notification Object

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

ParameterRequiredTypeDescription
to_sms_phonefalsestringThe SMS phone number of the notification
to_emailfalsestringThe email address of the notification
languagefalsestringThe 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.

ParameterRequiredTypeDescription
tokenfalsestringThis 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.
expirationfalsestringThe expiration of the request token in ISO 8601 date/time format.
approval_urlfalsestringThe 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.