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
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. |
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
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"
}
]
}
}
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.