Integration Guide
Sezzle Integration Guide
Using the Sezzle API
Obtain Authentication Token
POST https://gateway.sezzle.com/v2/authentication
Sezzle uses scoped API keys to allow access to the API. You can find/generate these keys on your merchant dashboard once you have been approved by Sezzle.
Once you have a valid token, it must be used as a Header for subsequent requests to our API, using the format below.
Authorization: Bearer authToken
To authorize, use the following format:
Request Body
{
"public_key": "myPublicKey",
"private_key": "myPrivateKey"
}
Make sure to replace
keys
with your API keys from your Merchant Dashboard.
Response Body
{
"token": "authToken",
"expiration_date": "2017-01-01T01:30:25.388940303Z",
"merchant_uuid": "merchant1234567890"
}
Open API
The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.
Specification
View the Sezzle v2 OpenAPI Specification.
Client Generator
The OpenAPI Specification can be imported into the Swagger Editor to easily generate a Sezzle client in a variety of programming languages. If your language is not supported by Swagger, an alternate tool is OpenAPI Generator.
Postman Setup
The Sezzle team has prepared a public Postman collection so merchants can quickly create customers (Sezzle users), sessions, and orders for sandbox testing.
Download and Install Postman
First, download and install the Postman application. To do this:
- Go to www.postman.com/downloads/
- Click Download the App.
- When the installation file has finished downloading, click the file to install the application.
- Follow installation prompts on the screen.
Add Sezzle Gateway Collection
When installation is complete, follow these steps to add the Sezzle Gateway collection to Postman.
- Click Run in Postman below to run the collection.
- In the Web page that opens, select your operating system.
- Click Open Postman if prompted.
- In Postman, the Sezzle Gateway collection is now displayed in the Collections tab.
Edit collection variables
Next, copy your credentials from the Sandbox Dashboard into the Sezzle Gateway collection variables in Postman. These are identifying variables that will apply across the collection.
To add your credentials to Postman:
- In Postman, select Sezzle Gateway to open the collection tab.
- In the collection tab, click Variables. This tab will store your credentials that apply across the collection.
- To access your credentials, log in to the Sandbox Dashboard
- Go to Settings > API Keys - your sandbox credentials are here.
- In Postman, paste your credentials into both INITIAL VALUE and CURRENT VALUE columns for:
- public_key
- private_key
Sandbox Testing
Before going live, you can test your integration with Sezzle using the Sezzle sandbox test environment, rather than the live production environment.
-
If a merchant registers for a Sezzle production account the merchant also automatically has sandbox access. A user given default admin access to the production dashboard also has access to the sandbox.
-
A merchant can also register a sandbox account to run tests without registering for a production account, if for example the merchant is integrating the production functions into their own system and don’t want to be a merchant in the Sezzle system.
- Access the sandbox: https://sandbox.dashboard.sezzle.com/merchant
- Log in using your Sezzle Merchant dashboard credentials.
- From the menu at the left select Settings > API Keys
- Click the button labeled *create API key
- Follow the prompts to create public and private API keys
NOTE: Though you can use same login for both sandbox and production dashboards, the API keys for these are not interchangeable. That is, you cannot use the sandbox API keys for the production dashboard, and vice versa.
- Create an order on your store website using the example data below.
- Select Sezzle as the payment method.
- Verify that the order goes through.
User Test Data
Phone and Personal Information
- Use any valid US or CA phone number, real or fake.
- The expected OTP is
123123
. - Personal information does not need to be real.
Credit Card
Account Number | 4242424242424242 |
CVV/CVC | any (3 numbers) |
Expiration Date | any |
Name | any |
Address | any |
Click here for more test cards, including more countries.
Errors
v2 endpoints will return an array of standardized error objects.
We attempt to keep these errors as consistent as possible, and will announce any changes in advance if they are required.
Error Response Body
[
{
"code": "invalid",
"location": "order.amount.amount_in_cents",
"message": "Order amount must be greater than $35",
"debug_uuid": "919f40d0-874b-4d98-810d-ed2246a8ad77"
}
]
Sessions
A session can be used to create an order, tokenize a customer, or both. Use the session endpoints to post a new session or get the details of an existing session.
Create a session
POST https://gateway.sezzle.com/v2/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.
Below is an example for creating an order checkout.
Request Body
{
"cancel_url": {
"href": "https://example.com/cart",
"method": "GET"
},
"complete_url": {
"href": "https://example.com/ord_12345/complete",
"method": "GET"
},
"customer": {
"email": "[email protected]",
"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"
}
}
}
Response Body
{
"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"
}
]
}
}
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.
Below is a simple example for tokenizing a customer. Providing more customer data will help expedite the registration process for any new Sezzle users.
Request Body
{
"cancel_url": {
"href": "https://example.com/user/payments",
"method": "GET"
},
"complete_url": {
"href": "https://example.com/user/payments/add-sezzle",
"method": "GET"
},
"customer": {
"tokenize": true
}
}
Response Body
{
"uuid": "fadbc642-05a4-4e38-9e74-80e325623af9",
"links": [
{
"href": "https://gateway.sezzle.com/v2/session/fadbc642-05a4-4e38-9e74-80e325623af9",
"method": "GET",
"rel": "self"
}
],
"tokenize": {
"token": "7ec98824-67cc-469c-86ab-f9e047f9cf1a",
"expiration": "2020-04-27T14:46:59Z",
"approval_url": "https://dashboard.sezzle.com/customer/checkout-approval?merchant-request-id=3f3244fd-78ce-4994-af0c-b8c760d47794",
"links": [
{
"href": "https://gateway.sezzle.com/v2/token/7ec98824-67cc-469c-86ab-f9e047f9cf1a/session",
"method": "GET",
"rel": "token"
}
]
}
}
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.
Session Object
A valid session object contains at a minimum an Order object or a Customer object with tokenize set to true.
Parameter | Type | Description |
---|---|---|
cancel_url* | object | The HTTP request information used to redirect the customer in the case of a cancellation |
complete_url* | object | The HTTP request infromation used to redirect the customer upon completion of the session |
customer | object | The customer for this session |
order | object | The order for this session |
URL Object
This is used for both the cancel and complete URL objects
Parameter | Type | Description |
---|---|---|
href* | string | The URL used when redirecting a customer |
method | 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
Parameter | Type | Description |
---|---|---|
tokenize | boolean | Determines whether to tokenize customer. If omitted, will default to false. |
string | The customer's email address | |
first_name | string | The customer's first name |
last_name | string | The customer's last name |
phone | string | The customer's phone number |
dob | string | The customer's date of birth in YYYY-MM-DD format (parameter is input only) |
billing_address | object | The customer's billing address |
shipping_address | object | The customer's shipping address |
Address Object
This format is used for both billing_address and shipping_address in the Customer object.
Parameter | Type | Description |
---|---|---|
name | string | The name on the address |
street | string | The street and number of the address |
street2 | string | The apt or unit |
city | string | The city |
state | string | The 2 character state code |
postal_code | string | The postal delivery code |
country_code | string | The 2 character country code |
phone_number | string | The phone number at the delivery location |
Order Object
Parameter | Type | Description |
---|---|---|
intent* | 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* | string | Your reference ID for this order |
description* | string | Your description for this order |
order_amount* | object | A Price object containing the amount of the order, which must be at least 100 . All fields of the Price object are required. |
requires_shipping_info | 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 | array | The financing options of the checkout. Only one option can be included. |
items | object | The items being purchased |
discounts | object | The discounts applied to this order. Must be included in total |
metadata | 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 | object | The shipping fees applied to this order. Must be included in the total |
tax_amount | object | The taxes applied to this order. Must be included in the total |
checkout_expiration | string | The expiration for the order checkout in ISO 8601 date/time format |
checkout_mode | 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 | object | A Notification object for sending checkout URL to the customer |
locale | string | Localizes the checkout. Accepted values are en-US (English, United States), en-CA (English, Canada), fr-CA (French, Canada) and de-DE (German, Germany), Defaults to en-US if not provided. |
Item Object
Parameter | Type | Description |
---|---|---|
name | string | The name of the item |
sku | string | The sku identifier |
quantity | int | The quantity purchased |
price | object | The price object |
Discount Object
Parameter | Type | Description |
---|---|---|
name | string | The description of the discount |
amount | 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 | Type | Description |
---|---|---|
some_field_name | string | Custom metadata field |
some_other_field_name | 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 | Type | Description |
---|---|---|
amount_in_cents | int | The amount of the item in cents |
currency | 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 | Type | Description |
---|---|---|
to_sms_phone | string | The SMS phone number of the notification |
to_email | string | The email address of the notification |
language | 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 | Type | Description |
---|---|---|
token | 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 | string | The expiration of the request token in ISO 8601 date/time format. |
approval_url | string | The URL for the user to accept tokenization. This URL does not create an order, it is only used for tokenizing a customer. |
Get a session
GET https://gateway.sezzle.com/v2/session/{session_uuid}
You can retrieve the details of an existing session using this endpoint.
Response Body
Note: This example response is a multi-purpose session
{
"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",
"intent": "CAPTURE",
"checkout_url": "https://checkout.sezzle.com/?id=12a34bc5-6de7-890f-g123-4hi1238jk902",
"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"
}
]
},
"tokenize": {
"token": "7ec98824-67cc-469c-86ab-f9e047f9cf1a",
"expiration": "2020-04-27T14:46:59Z",
"approval_url": "https://dashboard.sezzle.com/customer/checkout-approval?merchant-request-id=3f3244fd-78ce-4994-af0c-b8c760d47794",
"links": [
{
"href": "https://gateway.sezzle.com/v2/token/7ec98824-67cc-469c-86ab-f9e047f9cf1a/session ",
"method": "GET",
"rel": "token"
}
]
}
}
Orders
Use the orders endpoints to get order details, update an order, release an amount by order, capture an amount by order, or refund an amount by order.
The {order_uuid} is the value returned from Create session (order.uuid) or Create order by customer (uuid). It is a different value than the Order ID displayed in the Sezzle Merchant Dashboard. It is important to note the Merchant Dashboard Order ID is not generated until a checkout is completed at Sezzle, whereas the {order_uuid} can represent an order before and after checkout completion.
Order payment flow

- Merchant calls
/v2/session
with order and intent ofAUTH
orCAPTURE
. Optionally, the merchant can send customer information. - Sezzle returns order uuid and checkout URL.
- Merchant redirects customer to Sezzle checkout URL.
- Customer completes the Sezzle checkout and is redirected to the session complete URL.
- If the intent was to
CAPTURE
, Sezzle will capture the total order amount. - If the intent was to
AUTH
, Sezzle will only authorize the total order amount and the merchant can call/v2/order
later to release or capture amounts using the order uuid.
Get an order
GET https://gateway.sezzle.com/v2/order/{order_uuid}
Use this endpoint to get details on an existing order
Response Body
{
"uuid": "12a34bc5-6de7-890f-g123-4hi1238jk902",
"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"
}
],
"intent": "AUTH",
"reference_id": "ord_12345",
"description": "sezzle-store - #12749253509255",
"checkout_expiration": "2022-03-30T21:59:17Z",
"checkout_status": "active",
"metadata": {
"location_id": "123",
"store_name": "Downtown Minneapolis",
"store_manager": "Jane Doe"
},
"order_amount": {
"amount_in_cents": 10000,
"currency": "USD"
},
"items": [
{
"name": "widget",
"sku": "sku123456",
"quantity": 1,
"price": {
"amount_in_cents": 1000,
"currency": "USD"
}
}
],
"customer": {
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"phone": "5555045294",
"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"
}
},
"authorization": {
"authorization_amount": {
"amount_in_cents": 10000,
"currency": "USD"
},
"approved": true,
"expiration": "2020-04-23T16:13:44Z",
"financing_option": "4-pay-biweekly",
"sezzle_order_id": "order-id-in-merchant-dashboard",
"releases": [
{
"uuid": "4b4d217c-18f1-4bfb-996e-767470c04661",
"amount": {
"amount_in_cents": 3000,
"currency": "USD"
}
}
],
"captures": [
{
"uuid": "f4415e94-e562-47cc-94f3-92279f27dc20",
"amount": {
"amount_in_cents": 7000,
"currency": "USD"
}
}
],
"refunds": [
{
"uuid": "83162d2f-d5f1-43ad-91ed-e8231920ce6d",
"amount": {
"amount_in_cents": 1000,
"currency": "USD"
}
}
]
}
}
Update an order
PATCH https://gateway.sezzle.com/v2/order/{order_uuid}
Use this endpoint to update an existing order. Only the reference ID can be updated.
Update Order Object
Parameter | Type | Description |
---|---|---|
reference_id* | string | Your reference ID for this order |
Request Body
{
"reference_id": "ord_9876"
}
There is no response body for this request. If successful, we return an HTTP 204 Status No Content.
Release amount by order
POST https://gateway.sezzle.com/v2/order/{order_uuid}/release
Use this endpoint to release an amount by order.
Header Parameters
Parameter | Type | Description |
---|---|---|
Sezzle-Request-Id | string | A unique, merchant-generated ID. Use this header to enforce idempotency when releasing an authorization. |
Release Order Object
A price object
Price Object
Parameter | Type | Description |
---|---|---|
amount_in_cents* | number | The amount in cents to release on this order |
currency* | string | The 3 character currency code as defined by ISO 4217 |
Request Body
{
"amount_in_cents": 5000,
"currency": "USD"
}
Response Body
{
"uuid": "6c9db5d4-d09a-4224-860a-b5438ac32ca8"
}
The uuid returned from this operation is the release transaction uuid, but there are no
endpoints that use this value. You may retrieve an order's release transactions using the
Get an order endpoint.
Capture amount by order
POST https://gateway.sezzle.com/v2/order/{order_uuid}/capture
Use this endpoint to capture an amount by order.
Header Parameters
Parameter | Type | Description |
---|---|---|
Sezzle-Request-Id | string | A unique, merchant-generated ID. Use this header to enforce idempotency when capturing an order. |
Capture Amount By Order Object
Parameter | Type | Description |
---|---|---|
capture_amount* | object | Details the amount and currency being captured |
Capture Amount Object
A price object.
Price Object
Parameter | Type | Description |
---|---|---|
amount_in_cents* | string | The amount in cents to be captured |
currency* | string | The 3 character currency code as defined by ISO 4217 |
Request Body
{
"capture_amount": {
"amount_in_cents": 5000,
"currency": "USD"
}
}
Response Body
{
"uuid": "6c9db5d4-d09a-4224-860a-b5438ac32ca8"
}
The uuid returned from this operation is the capture transaction uuid, but there are no
endpoints that use this value. You may retrieve an order's capture transactions using the
Get an order endpoint.
Refund amount by order
POST https://gateway.sezzle.com/v2/order/{order_uuid}/refund
Use this endpoint to refund an amount by order
Header Parameters
Parameter | Type | Description |
---|---|---|
Sezzle-Request-Id | string | A unique, merchant-generated ID. Use this header to enforce idempotency when refunding an order. |
Refund Amount Object
A price object.
Price Object
Parameter | Type | Description |
---|---|---|
amount_in_cents* | string | The amount in cents to be refunded |
currency* | string | The 3 character currency code as defined by ISO 4217 |
Request Body
{
"amount_in_cents": 5000,
"currency": "USD"
}
Response Body
{
"uuid": "6c9db5d4-d09a-4224-860a-b5438ac32ca8"
}
The uuid returned from this operation is the refund transaction uuid, but there are no
endpoints that use this value. You may retrieve an order's refund transactions using the
Get an order endpoint.
Reauthorize amount by order
POST https://gateway.sezzle.com/v2/order/{order_uuid}/reauthorize
Use this endpoint to reauthorize an amount by order. An order can only be reauthorized after the initial authorization has expired. Any attempts to reauthorize before the authorization expires will fail. An authorization can be released before expiration, thus allowing the order to be reauthorized.
Please note the following when reauthorizing an order.
- A new order will be created
- The
intent
will be set toAUTH
- The
reference_id
will be the same as the original order
- The
- The reauthorized amount will be a new installment plan for the customer
Header Parameters
Parameter | Type | Description |
---|---|---|
Sezzle-Request-Id | string | A unique, merchant-generated ID. Use this header to enforce idempotency when refunding an order. |
Reauthorize Amount Object
A price object.
Price Object
Parameter | Type | Description |
---|---|---|
amount_in_cents* | string | The amount in cents to be reauthorized |
currency* | string | The 3 character currency code as defined by ISO 4217 |
Request Body
{
"amount_in_cents": 5000,
"currency": "USD"
}
Response Body
{
"uuid": "6c9db5d4-d09a-4224-860a-b5438ac32ca8",
"links": [
{
"href": "https://gateway.sezzle.com/v2/order/6c9db5d4-d09a-4224-860a-b5438ac32ca8",
"method": "GET",
"rel": "self"
}
],
"intent": "AUTH",
"reference_id": "original_order_reference_id",
"order_amount": {
"amount_in_cents": 5000,
"currency": "USD"
},
"authorization": {
"authorization_amount": {
"amount_in_cents": 5000,
"currency": "USD"
},
"approved": true,
"expiration": "2022-04-23T16:13:44Z"
}
}
Reauthorization Approval
Reauthorizations are not guaranteed to be approved. It is extremely important to note this API will return a 200 success if the request to reauthorize is successful (i.e. no errors) but the customer was not approved. Please be sure to check the authorization approved value to determine if the reauthorization order was created.
Delete checkout by order
DELETE https://gateway.sezzle.com/v2/order/{order_uuid}/checkout
Use this endpoint to delete a checkout for an order. The request fails if the checkout has already
been successfully completed by the customer.
If you have redirected the customer to the Sezzle checkout and subsequently cancel the order in
your ecommerce platform, then you should immediately call this endpoint to prevent the possibility
of the customer completing the Sezzle checkout.
There is no response body for this request. If successful, we return an HTTP 204 Status No Content.
Settlement Reports
These endpoints allow you to view a list of payout summaries or a detailed report of an individual payout.
Settlement Summaries Request
GET https://gateway.sezzle.com/v2/settlements/summaries
Query Parameter | Description |
---|---|
start-date* | The UTC start date for the report. Must be in yyyy-mm-dd format. |
end-date | The UTC end date for the report. Must be in yyyy-mm-dd format. If omitted, will default to the current date. |
offset | The offset for the report. Limit is 20. |
currency-code | The ISO-4217 currency code selected by users at checkout. If omitted, will default to USD. |
Multi-Currency
If your store accepts multiple currencies, you will need to request settlement summaries for each supported currency. If currency code is not provided in the request, the default currency will be USD.
Settlement Summaries Response Body
[
{
"uuid": "b7916fbe-f30a-4435-b411-124634287a8ca",
"payout_currency": "USD",
"payout_date": "2019-12-09T15:52:33Z",
"net_settlement_amount": 9370,
"forex_fees": 0,
"status": "Complete"
},
{
"uuid": "c51343hba-d54b-5641-e341-15235523b3at",
"payout_currency": "USD",
"payout_date": "2019-12-10T15:52:33Z",
"net_settlement_amount": 23470,
"forex_fees": 0,
"status": "Complete"
}
]
Settlement Details Request
GET https://gateway.sezzle.com/v2/settlements/details/{payout_uuid}
Query Parameter | Description |
---|---|
metadata | An optional comma-separated list of metadata keys. To add a metadata key as a column to the report line items, include the key in this list. When applicable, the value of the metadata key will be added to the line item. If no line items contain the metadata key, the key will not be added as a column. |
Settlement Details Response
total_order_amount,total_capture_amount,total_refund_amount,total_fee_amount,total_returned_fee_amount,total_chargeback_amount,total_chargeback_reversal_amount,total_interest_transfer_amount,total_correction_amount,total_referral_revenue_transfer_amount,total_bank_account_withdrawals,total_bank_account_withdrawal_reversals,forex_fees,net_settlement_amount,payment_uuid,settlement_currency,payout_date,payout_status
703.20,1.80,-5.00,-43.80,.30,0.00,0.00,-4.30,1.71,10.00,100.00,-100.00,0.00,693.61,a5c13qt1-4126-41d3-2fq8-9ca431f51431,USD,2019-11-02 00:05:00 +0000 UTC,Complete
type,order_capture_date,order_created_at,event_date,order_uuid,customer_order_id,external_reference_id,order_amount,amount,posting_currency,type_code,chargeback_code,sezzle_order_id,product_type,mid,card_network_auth_ref
ORDER,2019-11-01T19:09:50Z,2019-11-01T19:09:50Z,2019-10-22T19:09:50Z,bm99f-31vu1-kg00e-rae1g,1,12345,500.00,,USD,001,,66d78e86-fd96-4266-9217-b769c102a0a0,standard_checkout,,
ORDER,2019-11-01T19:09:50Z,2019-11-01T19:09:50Z,2019-10-22T19:09:50Z,va13d-474s9-3000e-nungg,13,12346,200.00,,USD,001,,5e0d4886-8c3d-4d4e-901a-2046a06c1e0f,long_term_lending,,
ORDER,2019-11-01T20:00:01Z,2019-11-01T00:00:01Z,2019-11-01T00:00:01Z,as41g-4v4s9-3000e-nunh0,1,12347,1.40,,USD,001,,a2c1a142-96ad-48c9-93d2-1acaaee9f073,four_pay_monthly,,
ORDER,2019-11-01T20:00:01Z,2019-11-01T20:00:01Z,2019-11-01T20:00:01Z,as62l-5ptqs-9g00e-pvk10,2,12348,1.80,,USD,001,,3f62dcba-f5a4-41be-ad8f-53e938b5f310,six_pay_monthly,,
CAPTURE,2019-11-01T20:00:01Z,2019-11-01T20:00:01Z,2019-11-01T20:00:01Z,as62l-5ptqs-9g00e-pvk10,2,12348,,1.80,USD,001,,3f62dcba-f5a4-41be-ad8f-53e938b5f310,affiliate,,
FEE,2019-11-01T19:09:50Z,2019-11-01T19:09:50Z,2019-11-01T19:09:50Z,bm99f-31vu1-kg00e-rae1g,1,12345,,-30.00,USD,003,,66d78e86-fd96-4266-9217-b769c102a0a0,standard_checkout,,
FEE,2019-11-01T19:09:50Z,2019-11-01T19:09:50Z,2019-11-01T19:09:50Z,va13d-474s9-3000e-nungg,13,12346,,-12.00,USD,003,,5e0d4886-8c3d-4d4e-901a-2046a06c1e0f,pay_in_full,,
FEE,2019-11-01T20:00:01Z,2019-11-01T00:00:01Z,2019-11-01T20:00:01Z,as41g-4v4s9-3000e-nunh0,1,12347,,-1.20,USD,003,,a2c1a142-96ad-48c9-93d2-1acaaee9f073,standard_checkout,,
FEE,2019-11-01T20:00:01Z,2019-11-01T20:00:01Z,2019-11-01T20:00:01Z,as62l-5ptqs-9g00e-pvk10,2,12348,,-0.60,USD,003,,3f62dcba-f5a4-41be-ad8f-53e938b5f310,affiliate,,
REFUND,2019-10-22T19:09:50Z,2019-10-22T19:09:50Z,2019-11-01T19:09:50Z,bm5rm-vg2js-1tsky-c2dsky,8,12344,,5.00,USD,002,,e4194956-de70-4958-9da4-6c05f276fdab,gift_card,,
RETURNED_FEE,2019-10-22T19:09:50Z,2019-10-22T19:09:50Z,2019-11-01T19:09:50Z,bm5rm-vg2js-1tsky-c2dsky,7,12344,,.30,USD,004,,e4194956-de70-4958-9da4-6c05f276fdab,long_term_lending,,
CORRECTION,,,2019-11-01T17:00:01Z,,,,,-1.29,,007,
CORRECTION,,,2019-11-01T17:00:01Z,,,,,3.00,,007,
INTEREST_TRANSFER,,,2019-11-01T18:00:01Z,,,,,-4.30,,008,
REFERRAL_REVENUE_TRANSFER,,,2019-11-01T15:00:01Z,,,,,10.00,,009,
BANK_ACCOUNT_WITHDRAWAL,,,2019-11-02T00:05:00Z,,,,,100.00,,010,
BANK_ACCOUNT_WITHDRAWAL_REVERSAL,,,2019-11-02T00:05:00Z,,,,,-100.00,,011,
The settlement details response contains two sections. The first two rows are a summary of the payout. The remaining rows contain the individual line items that contributed to the payout.
Summary column definitions:
Column Header | Description |
---|---|
Total order amount | The sum of all orders on this payout. |
Total refund amount | The sum of all refunds on this payout. |
Total fee amount | The sum of all fees on this payout. |
Total returned fee amount | The sum of all returned fees on this payout. |
Total chargeback amount | The sum of all chargebacks on this payout. |
Total chargeback reversal amount | The sum of all chargeback reversals on this payout. |
Total interest transfer amount | The sum of all interest transfers on this payout. If you are not participating in the interest program, this field will be omitted. |
Total correction amount | The sum of all corrections on this payout. |
Total referral revenue transfer amount | The sum of all referral revenue transfers on this payout. |
Total bank account withdrawal amount | The sum of all bank account withdrawals. |
Total bank account withdrawal reversal amount | The sum of all bank account withdrawal reversals, which reflect a bank account withdrawal that has failed. |
Forex fees | The cost of foreign exchange fees associated with this payout. |
Net settlement amount | Net amount of settlement. |
Payment uuid | The UUID for this payout. |
Settlement currency | The currency in which this payout was sent. |
Payout date | The date this payout was sent. |
Payout status | The current status of this payout. |
Line item column definitions:
Column Header | Description |
---|---|
Type | Describes the type of event (Order, Fee, Refund, etc.). |
Order capture date | The date at which the order was captured. This field is empty if the order has not yet been captured. |
Order created at | The date at which the order was created. |
Event date | The date at which the event took place. |
Order uuid | The uuid associated with the order. |
Customer order id | The customer's order number. |
External reference id | The external reference ID submitted with the order. |
Order Amount | The order amount for the ORDER event |
Amount | The amount of the event. |
Posting currency | The customer's currency code. |
Type code | A numeric code that corresponds with the Type field. |
Chargeback code | A numeric code that corresponds with the type of chargeback submitted. |
Sezzle order ID | The internal ID Sezzle has assigned to this order. |
Product type | Describes the type of merchant product (Affiliate, Gift card, Standard_checkout, etc.) |
Merchant identification number (MID) | The ID that identifies the merchant and the legitimacy of the business and facilitates the movement of funds from the customer’s bank account to the merchant’s bank account. |
Card Network Auth Ref | A unique numeric or alphanumeric identifier assigned to credit card transactions, making it easier to locate and identify an individual credit card transaction. |
Line item event type definitions:
Type | Description | Type Code |
---|---|---|
ORDER | A completed order with Sezzle. | 001 |
REFUND | An order that has been refunded. | 002 |
FEE | The fee assessed by Sezzle for a given order. | 003 |
RETURNED_FEE | A fee refunded by Sezzle. | 004 |
CHARGEBACK | A chargeback resulting from a disputed order. | 005 |
CHARGEBACK_REVERSAL | A reversal of a chargeback resulting from a disputed order. | 006 |
CORRECTION | A manual correction to a payout. | 007 |
INTEREST_TRANSFER | A transfer from the Sezzle interest account. | 008 |
REFERRAL_REVENUE_TRANSFER | A payment earned from Sezzle's merchant referral program. | 009 |
BANK_ACCOUNT_WITHDRAWAL | A withdrawal of funds from your bank to cover a negative balance with Sezzle. | 010 |
BANK_ACCOUNT_WITHDRAWAL_REVERSAL | A failed BANK_ACCOUNT_WITHDRAWAL. | 011 |
CAPTURE | An order that has been captured. | 012 |
Line item product type definitions:
Type | Description |
---|---|
standard_checkout | Standard pay in four checkout |
four_pay_monthly | 4 pay monthly order |
six_pay_monthly | 6 pay monthly order |
long_term_lending | Base long term lending product with no promotions |
virtual_card | Virtual card order |
Interest Account Reports
Sezzle gives merchants the option to enroll in an interest account program. If you are enrolled in the interest account program, you can use these endpoints to get the current balance and activity on the interest account. Fractions of cents are tracked to properly calculate daily interest accrual even if the interest balance is low.
Interest Account Balance Request
GET https://gateway.sezzle.com/v2/interest/balance
Query Parameter | Description |
---|---|
currency-code | The ISO-4217 currency code of the interest account. If omitted, will default to USD. |
Interest Account Activity Request
GET https://gateway.sezzle.com/v2/interest/activity
Query Parameter | Description |
---|---|
start-date* | The start date for the report. Must be in yyyy-mm-dd format. |
end-date | The end date for the report. Must be in yyyy-mm-dd format. If omitted, will default to the current date. |
offset | The offset for the report. Limit is 20. |
currency-code | The ISO-4217 currency code of the interest account. If omitted, will default to USD. |
Interest Account Balance Response Body
{
"interest_balance": 5183.4624
}
Interest Account Activity Response Body
type,event_date,interest_account_change_amount,interest_account_balance_after_change
INTEREST_PAYOUT,2019-12-21T19:10:00Z,122.8718,5101.4676
INTEREST_WITHDRAWAL,2019-12-21T19:20:00Z,-26.1000,5075.3676
INTEREST_ACCRUAL,2019-12-21T19:15:00Z,1.0702,5182.3922
INTEREST_ACCRUAL,2019-12-22T19:15:00Z,1.0702,5183.4624
Tokenization
Customer tokenization
Customer tokenization is akin to adding Sezzle as a payment method on file with the merchant, thus allowing the merchant to use Sezzle as a payment method for future orders (without customer interaction). A primary use case for customer tokenization is subscriptions. For example, a merchant may choose to tokenize a customer in order to charge by Sezzle on a semi-annual basis.
A typical process of tokenizing a customer in Sezzle might be, a user is signed into the merchant site and the user wants to add Sezzle as a stored payment method. The merchant can start a session with Sezzle and assign the session UUID to the known user. The merchant will redirect the user to Sezzle and the user can agree to accept tokenization. Once the user accepts, Sezzle will redirect the user back to the merchant site and also append a unique customer UUID to the merchant URL, thus allowing the merchant to assign this customer UUID to the user that started the session. The customer UUID can now be used to create an order by customer directly with Sezzle. Orders created by customer are treated the same as orders created by completing a Sezzle checkout.
Tokenization is not required and only necessary if the merchant has a need to charge by Sezzle outside of a typical checkout process. Sezzle recommends tokenization on an as-needed basis.

- Merchant starts a session by calling
/v2/session
with customer tokenize oftrue
. Including customer information is optional, but it can expedite the registration process for new Sezzle users. - Sezzle returns the session
tokenize
token and an approval URL. - Merchant redirects customer to the Sezzle approval URL.
- Customer can agree (or disagree) to allow future Sezzle transactions by the merchant and is redirected to the session complete URL. If the customer agrees to be tokenized, Sezzle will add a query parameter to the complete URL named
customer-uuid
, allowing the merchant to get the UUID of the customer. Alternatively, the merchant can call/v2/token
with the sessiontokenize.token
to get the UUID of the customer. - Merchant can subsequently charge the customer by calling
/v2/customer/{customer_uuid}/order
to create an order. If successful and the authorization is approved, the merchant can use the/v2/order
endpoints to release, capture, or refund the order.
The merchant also has the option to create an order and tokenize the customer in a single session. In this instance, the merchant should redirect the customer to the order checkout URL. During checkout, the customer can agree to allow future Sezzle transactions by the merchant (i.e. accept tokenization). If the customer agrees to be tokenized, Sezzle will add a query parameter to the complete URL named customer-uuid
. Note: Sezzle returns both a checkout URL and an approval URL on a create session that includes both tokenization and an order. If the customer does not agree to be tokenized during checkout, the merchant can use the approval URL at a later time.
Get session tokenization
GET https://gateway.sezzle.com/v2/token/{token}/session
You can use this endpoint to get the current state of a tokenization session. If the customer is not tokenized, then the customer object will be omitted.
Response Body
{
"token": "4f8cf865-2089-4423-85fd-ea833a16b62d",
"expiration": "2020-04-29T19:31:54Z",
"links": [
{
"href": "https://gateway.sezzle.com/v2/token/4f8cf865-2089-4423-85fd-ea833a16b62d/session",
"method": "GET",
"rel": "self"
}
],
"customer": {
"uuid": "a9d8e15c-5e4a-4201-aa8f-7540f934a9a2",
"expiration": "2020-10-13T14:29:41Z",
"links": [
{
"href": "https://gateway.sezzle.com/v2/customer/a9d8e15c-5e4a-4201-aa8f-7540f934a9a2",
"method": "GET",
"rel": "self"
}
]
}
}
Customers
Customers are only those Sezzle users that have agreed to be tokenized by the merchant. A customer is unique to a merchant. This API does not include all Sezzle users.
Use the customers endpoints to get a list of customers, get details on an existing customer, delete a customer, preapprove an amount for the customer, or create an order for a customer.
Get a list of customers
GET https://gateway.sezzle.com/v2/customer
You can retrieve a list of existing customers using this endpoint.
Response Body
[
{
"uuid": "a9d8e15c-5e4a-4201-aa8f-7540f934a9a2",
"expiration": "2020-04-28T17:58:11Z",
"links": [
{
"href": "https://gateway.sezzle.com/v2/customer/a9d8e15c-5e4a-4201-aa8f-7540f934a9a2",
"method": "GET",
"rel": "self"
},
{
"href": "https://gateway.sezzle.com/v2/customer/a9d8e15c-5e4a-4201-aa8f-7540f934a9a2",
"method": "DELETE",
"rel": "self"
},
{
"href": "https://gateway.sezzle.com/v2/customer/a9d8e15c-5e4a-4201-aa8f-7540f934a9a2/preapprove",
"method": "POST",
"rel": "preapprove"
},
{
"href": "https://gateway.sezzle.com/v2/customer/a9d8e15c-5e4a-4201-aa8f-7540f934a9a2/order",
"method": "POST",
"rel": "order"
}
]
}
]
Get a customer
GET https://gateway.sezzle.com/v2/customer/{customer_uuid}
You can use this endpoint to get details on an existing customer
Response Body
{
"uuid": "a9d8e15c-5e4a-4201-aa8f-7540f934a9a2",
"links": [
{
"href": "https://gateway.sezzle.com/v2/customer/a9d8e15c-5e4a-4201-aa8f-7540f934a9a2",
"method": "GET",
"rel": "self"
},
{
"href": "https://gateway.sezzle.com/v2/customer/a9d8e15c-5e4a-4201-aa8f-7540f934a9a2",
"method": "DELETE",
"rel": "self"
},
{
"href": "https://gateway.sezzle.com/v2/customer/a9d8e15c-5e4a-4201-aa8f-7540f934a9a2/preapprove",
"method": "POST",
"rel": "preapprove"
},
{
"href": "https://gateway.sezzle.com/v2/customer/a9d8e15c-5e4a-4201-aa8f-7540f934a9a2/order",
"method": "POST",
"rel": "order"
}
],
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"phone": "5555045294",
"dob": "1990-02-25",
"token_expiration": "2020-04-27T14:46:59Z",
"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"
}
}
Delete a customer
DELETE https://gateway.sezzle.com/v2/customer/{customer_uuid}
You can use this endpoint to delete an existing customer
There is no response body for this request. If successful, we return an HTTP 204 Status No Content.
Preapprove amount by customer
POST https://gateway.sezzle.com/v2/customer/{customer_uuid}/preapprove
You can use this endpoint to preapprove an amount for a customer. The primary purpose of this API is for the merchant to verify a customer will be approved for the order amount prior to creating an order. This API does not authorize the amount nor does it hold the amount for a future order. Also, you are not required to use this API before creating a customer order.
An example use case is, a merchant intends to charge a customer by Sezzle for an upcoming subscription payment. The merchant could check a day or two in advance of the payment to confirm the order will be approved. If not, the merchant could reach out to the customer requesting the Sezzle account be updated prior to the payment date to avoid a potential failed payment.
Request Body
{
"amount_in_cents": 5000,
"currency": "USD"
}
Preapprove Object
A price Object
Price Object
Parameter | Type | Description |
---|---|---|
amount_in_cents* | number | The amount in cents to preapprove |
currency* | string | The 3 character currency code as defined by ISO 4217 |
Response Body
{
"uuid": "6c9db5d4-d09a-4224-860a-b5438ac32ca8",
"approved": true
}
Create order by customer
POST https://gateway.sezzle.com/v2/customer/{customer_uuid}/order
You can use this endpoint to create an order for a customer
Header Parameters
Parameter | Type | Description |
---|---|---|
Sezzle-Request-Id | string | A unique, merchant-generated ID. Use this header to enforce idempotency when authorizing order payment. |
Request Body
{
"intent": "AUTH",
"reference_id": "annual_sub_123",
"order_amount": {
"amount_in_cents": 5000,
"currency": "USD"
}
}
Order Payment Object
Parameter | Type | Description |
---|---|---|
intent* | string | Accepted values are "AUTH" or "CAPTURE" |
reference_id* | string | A reference ID for the order |
order_amount* | object | The amount and currency of the order |
financing_options | array | The financing option of the order. Only one option can be included. |
Order Amount Object
A price object. The amount must be greater than 99.
Price Object
Parameter | Type | Description |
---|---|---|
amount_in_cents* | number | The order amount in cents |
currency* | string | The 3 character currency code as defined by ISO 4217 |
Response Body
{
"uuid": "6c9db5d4-d09a-4224-860a-b5438ac32ca8",
"links": [
{
"href": "https://gateway.sezzle.com/v2/order/6c9db5d4-d09a-4224-860a-b5438ac32ca8",
"method": "GET",
"rel": "self"
},
{
"href": "https://gateway.sezzle.com/v2/order/6c9db5d4-d09a-4224-860a-b5438ac32ca8",
"method": "PATCH",
"rel": "self"
},
{
"href": "https://gateway.sezzle.com/v2/order/6c9db5d4-d09a-4224-860a-b5438ac32ca8/release",
"method": "POST",
"rel": "release"
},
{
"href": "https://gateway.sezzle.com/v2/order/6c9db5d4-d09a-4224-860a-b5438ac32ca8/capture",
"method": "POST",
"rel": "capture"
},
{
"href": "https://gateway.sezzle.com/v2/order/6c9db5d4-d09a-4224-860a-b5438ac32ca8/refund",
"method": "POST",
"rel": "refund"
}
],
"intent": "AUTH",
"reference_id": "annual_sub_123",
"order_amount": {
"amount_in_cents": 5000,
"currency": "USD"
},
"authorization": {
"authorization_amount": {
"amount_in_cents": 5000,
"currency": "USD"
},
"approved": true,
"expiration": "2020-04-23T16:13:44Z"
}
}
Order Approval
It is extremely important to note this API will return a 200 success if the request to create an order is successful (i.e. no errors) but the customer was not approved. Please be sure to check the authorization approved value to determine if the order was created.
Webhooks
You can use these endpoints to configure your webhooks
Create webhooks
POST https://gateway.sezzle.com/v2/webhooks
This endpoint can be used to subscribe to webhooks
Request Body
{
"url": "https://example.com/webhooks",
"events": [
"customer.tokenized"
]
}
Webhooks Object
Parameter | Type | Description |
---|---|---|
url* | string | The url you are using to receive webhooks |
events* | array | An array of events to subscribe to |
Response Body
{
"uuid": "747cf28a-bb5c-46a8-a288-d9b006fd6113",
"links": [ ]
}
Valid Webhook Events
We accept the following Webhook events
Event | Description |
---|---|
customer.tokenized | This webhook is called when a customer is tokenized |
order.authorized | This webhook is called when an order is authorized by Sezzle |
order.captured | This webhook is called when an order is captured by Sezzle |
order.refunded | This webhook is called when an order is refunded by Sezzle |
List webhooks
GET https://gateway.sezzle.com/v2/webhooks
You can get a list of your webhooks using this endpoint
Response Body
[
{
"uuid": "747cf28a-bb5c-46a8-a288-d9b006fd6113",
"links": [ ],
"url": "https://example.com/webhooks",
"events": [
"customer.tokenized"
]
}
]
Delete webhooks
DELETE https://gateway.sezzle.com/v2/webhooks/{webhooks_uuid}
You can delete your webhooks using this endpoint
There is no response body for this request. If successful, we return an HTTP 204 Status No Content.
Test Webhooks
POST https://gateway.sezzle.com/v2/webhooks/test
You can trigger a test event using this endpoint
Test Webhooks Object
Parameter | Type | Description |
---|---|---|
event* | string | One of the Valid Webhook Events |
url | string | A url to receive the test webhook. If omitted, the test webhook is sent to all urls subscribed to that event (see List Webhooks) |
There is no response body for this request. If successful, we return an HTTP 201 Status Created.
Webhook Signature
Webhooks are signed with an HMAC using the SHA256 algorithm. The header Sezzle-Signature
value is a hash of the webhook's body with your merchant private key. You should always verify that the signature matches the webhook data to ensure that the webhook came from Sezzle.
Webhook Acceptance and Retries
A webhook has been successfully sent when we receive an HTTP 200 Status OK response. Any other response will queue the webhook to be retried. We will retry several times within the first hour, and a few times for the remainder of that day. The final two attempts are made one day later, and then 3 days later, for a total elapsed time of five days. If the final retry fails, then that subscribed webhook will be deleted for all events. You will need to create the webhook again to resubscribe, if desired.
It is possible that new webhooks will arrive before old webhooks have been retried, so webhooks are not guaranteed to be received in cronological order.
Webhooks are signed using the current merchant private key, not the private key at the time of their creation, so a retried webhook may have a different signature if the keys are changed after its originating event.
SDK
Javascript SDK
The Javascript SDK can be used for a simple, lightweight integration, but it also includes an in-context mode which will host the Sezzle checkout in a modal iframe or pop-up window.
Javascript SDK Features
- Create Checkout
- Capture Payment
- Supports Sezzle Checkout in an iframe, pop-up window, or redirect to Sezzle
- Handle Payment Success
- Handle Payment Cancel
- Handle Payment Failure
- Render Sezzle Button
Installing the Javascript SDK
- Include
https://checkout-sdk.sezzle.com/checkout.min.js
in the<head>
section of the page.
Implement the Javascript SDK
Button Configuration
-
Create a placeholder element for the Sezzle Button to be rendered on the page(s).
-
Use HTML attributes to customize the button.
Attribute | Description |
---|---|
templateText | Text that will prepended with the Sezzle logo. Default is Checkout with %%logo%% |
borderType | Options are square and semi-rounded |
customClass | Custom classes to be applied |
paddingX | X-axis padding. Default is 13px |
paddingY | Y-axis padding. Default is 7px |
width | Width of the button |
height | Height of the button. Default is 20% |
Button Placeholder
<div id="sezzle-smart-button-container"></div>
Button Customization
<div id="sezzle-smart-button-container" style="text-align: center"
templateText="Pay with %%logo%%"
borderType="semi-rounded"
customClass="action,primary,checkout">
</div>
Checkout Configuration
- Edit the page file to implement the SDK.
- Configure the SDK with the following options:
Attribute | Options |
---|---|
mode | redirect |popup |iframe |
apiMode | sandbox |live |
apiVersion | v2 |v1 |
publicKey* | xxxx (used only when creating a checkout or capturing payment) |
Configure Checkout
const checkout = new Checkout({
'mode': "popup",
'publicKey': "xxxx",
'apiMode': "sandbox",
'apiVersion': "v2"
});
For security reasons, Sezzle must enable an iframe for your site. To have it enabled, please submit a request with your Sezzle Merchant UUID and a list of domains to be allowed per environment (production and sandbox).
Render the Sezzle Button
Call renderSezzleButton
passing the id
of the placeholder element defined in Button Configuration, above.
Render Button
checkout.renderSezzleButton("sezzle-smart-button-container");
Get Installment Plan
This function will provide you the installment details based on the amount.
Get Installment Plan Implementation
checkout.getInstallmentPlan(1000);
Get Installment Plan Response
{
"schedule": "bi-weekly",
"totalInCents": 1000,
"installments": [
{
"installment": 1,
"amountInCents": 250,
"dueDate": "2020-10-14"
},
{
"installment": 2,
"amountInCents": 250,
"dueDate": "2020-10-28"
},
{
"installment": 3,
"amountInCents": 250,
"dueDate": "2020-11-11"
},
{
"installment": 4,
"amountInCents": 250,
"dueDate": "2020-11-25"
}
]
}
Initialize the Checkout
The SDK requires the following event handlers:
Event | Description |
---|---|
onClick* | Sezzle Button is clicked by the user |
onComplete* | Sezzle payment is successfully completed |
onCancel* | Sezzle payment is cancelled |
onFailure* | Sezzle payment has failed |
Initialize Checkout
checkout.init({
onClick: function () {},
onComplete : function (event) {},
onCancel: function () {},
onFailure: function (event) {}
});
Hosting the Checkout
To be implemented in the onClick
handler. There are two methods for hosting a checkout.
-
Use a checkout payload as detailed in the Session Object.
- The cancel and complete urls are not required for
iframe
andpopup
mode.
- The cancel and complete urls are not required for
-
Use an existing checkout url.
- The
mode
used when configuring the SDK checkout must match thecheckout_mode
when creating a session. - The parent window
origin
must be provided in the cancel and complete urls when thecheckout_mode
isiframe
orpopup
.
- The
-
Tokenization is not supported in the SDK.
Start Checkout with Payload
checkout.startCheckout({
checkout_payload: {
"order": {
"intent": "AUTH",
"reference_id": "ord_12345",
"description": "sezzle-store - #12749253509255",
"order_amount": {
"amount_in_cents": 10000,
"currency": "USD"
}
}
}
});
Start Checkout with URL
checkout.startCheckout({
checkout_url: "https://checkout.sezzle.com/?id=example"
});
Checkout Events
Events are only triggered in iframe
or popup
mode. The redirect
mode will instead redirect to the complete or cancel url.
- A successfully completed Sezzle checkout will trigger an event to the
onComplete
handler. The event should include adata
object with thesession_uuid
andorder_uuid
. - If the user exits the Sezzle checkout for any reason, the
onCancel
handler will be executed. - Any error will trigger an event to the
onFailure
handler. The event should include adata
object with the error details.
Checkout Completed
function onCompleteHandler(event) {
var data = event.data || Object.create(null);
console.log('checkout data:',
data.session_uuid,
data.order_uuid);
}
checkout.init({
onComplete : onCompleteHandler
});
Capture the Order
Typically implemented in the onComplete
handler. Capturing an order is not required if the CAPTURE
intent was used when creating the checkout.
The capture payment method requires two parameters, the order_uuid
and the payload as detailed in the Capture Amount By Order Object.
Capture Order
var payload = {
capture_amount: {
amount_in_cents: 5000,
currency: "USD"
}
};
checkout.capturePayment(data.order_uuid, payload);
Mobile SDK
The Mobile SDK is for integrating the Sezzle checkout and widget into a native mobile app.
Android
The Android SDK is available in Gradle or Maven.
iOS
The iOS SDK is available in CocoaPods.
Widget SDK
Purpose
Increase average order value and boost conversions!
The Sezzle promotional messaging widget conveniently informs shoppers of available financing as they browse.
Follow the documentation below to install the Sezzle widget on your product and cart pages.
Many of our top platforms have in-app one-click installation. If the one-click installation is not available for your platform or does not appear to be compatible with your theme, you may either follow the manual installation instructions below or reach out to [email protected]
The Sezzle promotional messaging widget installation requires two components: the "configuration" and the "script".
How It Works
When the page loads, the script will reach out to the widget-server to obtain the Javascript and configuration details. If a configuration is not found on the server, it will look for a local configuration.
If your site has a non-Shopify storefront, please install the script before requesting assistance.
Configuring the Widgets
Start with the basic configuration snippet here:
<script type="text/javascript">
document.sezzleConfig = {
"configGroups": [
{
"targetXPath": "YOUR IDENTIFIER HERE"
}
]
}
</script>
The document.sezzleConfig
object will accept the following keys, whose purpose and usage is outlined below:
configGroups (required)
Purpose: Allows multiple configurations for one store to suit different page types, layouts, or applications
Type: array of objects
Default: [{}]
Additional Details: Keys available for use within configGroups are outlined later in this document.
apDualInstall (optional)
Purpose: Afterpay's logo is appended to widget content. When clicked, the competitor's modal will display.
Type: boolean
Default: false
minPrice (optional)
Purpose: Minimum price in cents for which Sezzle can be selected at checkout. If the price at targetXPath
is lower than this number, the widget will render with a note stating the minimum eligible price required.
Type: number
Default: 0
Additional Details: This configuration does not prevent a customer from checking out with Sezzle below this price. For more information on setting a gateway minimum, contact your Merchant Success representative or use the Contact Us section of the Sezzle Merchant Dashboard.
maxPrice (optional)
Purpose: Maximum price in cents for which the widget should be rendered. If the price at targetXPath
is higher than this number, the widget will not render on the page.
Type: number
Default: 250000
language (optional)
Purpose: Language in which the widget text should be rendered.
Type: string
Options: 'en', 'fr', 'es'
Default: document.querySelector('html').lang
Additional Details: Currently, SezzleJS only supports 'en', 'fr', and 'es'. If the specified language is not supported, the translation will default to English.
observeElements (optional)
Purpose: Can attach event listeners to DOM element and re-initialize widget.
Type: array of objects
Additional Details: Each object should have an 'element' key with a string value containing an id or class & a valid 'eventType' such as 'click'
configGroups
Each object within the configGroups
array will accept the following keys, whose purpose and usage is outlined below:
targetXPath (required)
Purpose: ID, class, or path to the element in the webpage where the product price text value will be detected.
Type: string
Default: ''
Additional Details: To indicate a path, all subpaths need to be separated by the '/' character. IDs need to be preceded by a '#' character. Classes needed to be preceded by a '.' character. Tag names need to be followed by the applicable index. The format of a tag name is as follows: tagName-Index (e.g. 'SPAN-2'). The indexes are zero-based, such that the first element of the specified type within the parent element is at index 0.
Example: '#ProductSection/.product-price/SPAN-1' would target the 2nd 'SPAN' element contained within elements that contain the 'product-price' class which are contained within the element with an ID of 'ProductSection'.
renderToPath (optional)
Purpose: Path from the targetXPath to the element in the webpage after which the Sezzle widget should be rendered.
Type: string
Default: '..'
Additional Details: '.' will place the widget as the next element sibling of the target element. To move the widget to a parent container, use '../' for each parent level. You may then traverse downward using ID, class, tag-index, or pseudo-selectors. As with targetXPath, prepend IDs with '#', classes with '.', and append tag names with the index (tagName-Index). Append pseudo-selectors with '::'. It is recommended to keep the renderToPath as simple as possible to maximize compatibility.
Example: '../../BUTTON-0' would go to the grandparent element of the targetXPath and place the widget after the first button found within that container.
urlMatch (optional)
Purpose: Specific word appearing in the url of pages where the widget config should be applied.
Type: string
Default: ''
Additional Details: Typical values are 'product' or 'cart', as applicable
theme (optional)
Purpose: Updates the logo color to coordinate and contrast with different background colors of websites.
Type: string
Options: dark, light, black-flat, white-flat
Default: ''
Additional Details: If theme is not specified, the widget will attempt to detect the background color and apply the appropriate contrasting logo. Use "light" or "black-flat" for light backgrounds, and "dark" or "white-flat" for dark backgrounds.
containerStyle (optional)
Purpose: Custom styling to apply to the Sezzle widget container.
Type: object
Default: {}
Additional Details: The object will accept any CSS styling in JSON format. Keys must be surrounded by '', given in camelCase instead of kebob-case, and separated from the following key by a comma instead of a semi-colon.
textStyle (optional)
Purpose: Custom styling to apply to the Sezzle text within the widget.
Type: object
Default: {}
Additional Details: The object will accept any CSS styling in JSON format. Keys must be surrounded by '', given in camelCase instead of kebob-case, and separated from the following key by a comma instead of a semi-colon.
logoStyle (optional)
Purpose: Custom styling to apply to the Sezzle logo within the widget.
Type: object
Default: {}
Additional Details: The object will accept any CSS styling in JSON format. Keys must be surrounded by '', given in camelCase instead of kebob-case, and separated from the following key by a comma instead of a semi-colon.
relatedElementActions (optional)
Purpose: Functions related to Sezzle widget. Listen for changes on the webpage after the Sezzle widget loads.
Type: array of objects
Default: []
Additional Details: Each object in the array has three available keys: relatedPath
, which targets an element in relation to the targetXPath
(in the same manner as renderToPath
); action
; and initialAction
, with preset params corresponding to the relatedPath element and the current widget which performs the provided function as the widget is rendering
ignoredPriceElements (optional)
Purpose: Direct child elements of targetXPath
to be disregarded when detecting the price and rendering the widget.
Type: array of strings
Default: []
Additional Details: ignoredPriceElements
can be used to solve targetXPath
variations between sale and regular-priced items. In this case, targetXPath
should point to the parent element surrounding the old and the new prices, then ignoredPriceElements
will specify the old/compare-at price element. As with targetXPath
, prepend IDs with '#', classes with '.', and append tag names with the index (tagName-Index).
ignoredFormattedPriceText (optional)
Purpose: Text strings within the targetXPath
to be disregarded when detecting the price and rendering the widget.
Type: array of strings
Default: ['Subtotal', 'Total:', 'Sold Out']
hideClasses (optional)
Purpose: XPath of elements that should be hidden when Sezzle's widget is showing. This is useful for hiding a product similar to Sezzle that is not available in a country where Sezzle is.
Type: array of strings
Default: []
Additional Details: Despite what the name suggests, this config option accepts an array of xpaths. As with targetXPath
, prepend IDs with '#', classes with '.', and append tag names with the index (tagName-Index).
Example:
["#viabill-pricetag",".afterpay-paragraph","QUADPAYWIDGET-0"]
alignment (optional)
Purpose: Alignment of the widget relative to the parent element.
Type: string
Options: left, center, right, auto
Default: 'auto'
alignmentSwitchMinWidth (optional)
Purpose: Screen width in pixels below which the alignment switches to alignmentSwitchType
instead of alignment
.
Type: number
Default: 0
Additional Details: The most common breakpoint is 768 (handheld vs desktop). alignmentSwitchMinWidth
is typically only necessary when alignment is not auto.
alignmentSwitchType (optional)
Purpose: Alignment of the widget relative to the parent element to be applied when the viewport width is narrower than alignmentSwitchMinWidth
.
Type: string
Options: left, center, right, auto
Default: 'auto'
Example Widget Config
To further illustrate usage, please refer to the below example snippet:
<script type="text/javascript">
document.sezzleConfig = {
configGroups: [
{
"targetXPath": ".price",
"renderToPath": "..",
"urlMatch": "product",
"theme": "auto",
"ignoredPriceElements": ["DEL","STRIKE"],
"ignoredFormattedPriceText": ["Subtotal", "Total:", "Sold Out"],
"alignment": "inherit",
"alignmentSwitchMinWidth": 0,
"alignmentSwitchType": "inherit",
"containerStyle": {
"marginTop": "0px",
"marginBottom": "0px",
"marginRight": "0px",
"marginLeft": "0px"
},
"textStyle": {
"color": "inherit"
"fontFamily": "inherit",
"fontSize": "14px",
"fontWeight": 500,
"lineHeight": "13px",
"maxWidth": "480px"
},
"logoStyle": {
"transform": "scale(1)",
"transformOrigin": "center",
"margin": "0px"
},
"hideClasses": [],
"relatedElementActions": [{
"relatedPath": "..",
"initialAction": function(r,w){
if(r.className.indexOf('compare') > -1){
w.style.display = "none"
}
}
}]
}
],
"language": document.querySelector("html").lang || "en",
"apDualInstall": false,
"minPrice": 0,
"maxPrice": 250000,
"observeElements": [
{
"eventType": "click",
"element": ".options-selector"
}
]
}
</script>
Uploading the Widgets
After building up the config, it is time to upload the widgets to your webpages! The SDK needs to be called in the HTML of the webpage for the widgets to be rendered. Place the config and the widget script at the bottom of the code file for the HTML page, and you should be all set!
The script reflecting the applicable merchant ID must be called only after the config is specified (
document.sezzleConfig
is defined).
A pre-populated snippet should be provided in your Sezzle Merchant Dashboard Setup Checklist. If it is unavailable, you may start with the following snippet:
<script src="https://widget.sezzle.com/v1/javascript/price-widget?uuid=YOUR MERCHANT ID HERE"></script>
When using this snippet to add the widget script to your site, you must replace "YOUR MERCHANT ID HERE" with the 36-character Sezzle Merchant ID found in the Business Settings of your Sezzle Merchant Dashboard for the applicable store. Please do not re-use IDs across multiple URLs.
Updated 16 days ago