> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sezzle.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration
The Sezzle Express checkout button gives shoppers a single-click path to pay with Sezzle directly from the cart, using the contact and payment details on their Sezzle account. Fewer fields to fill in means fewer abandoned carts.
## Installation
### Include SDK code
Include the following script in the `` section of the page.
```html theme={"system"}
```
### Checkout Configuration
#### Configuration Options
```javascript theme={"system"}
const checkoutSdk = new Checkout({
mode: string,
publicKey: string,
apiMode: string,
apiVersion: string,
});
```
```javascript theme={"system"}
const checkoutSdk = new Checkout({
mode: "popup",
publicKey: "sz_pub_...",
apiMode: "live",
apiVersion: "v2",
});
```
Available options: `popup`, `iframe`, `redirect`
If you use `iframe` mode, add `*.sezzle.com` to your site's Content Security Policy (CSP) allowlist so the Sezzle checkout iframe can load.
* **popup** (recommended): works out of the box for most browser-based SDK integrations.
* **iframe**: required when popups are blocked (e.g. inside a webview or embedded browser). Sezzle must enable iframe for your domain(s) first — submit your Merchant UUID and the domains to allow per environment (sandbox and production). For example: *please enable uat1.mysite.com, uat2.mysite.com in sandbox and [www.mysite.com](http://www.mysite.com), mysite.com in production*.
* **redirect**: supported but generally less useful with the SDK, since the SDK's value is the in-context checkout and window messaging.
Used when creating a checkout or capturing payment. Find your API keys at [https://dashboard.sezzle.com/merchant/settings/apikeys](https://dashboard.sezzle.com/merchant/settings/apikeys)
Environment in which the checkout is to be completed
Available options: `live`, `sandbox`
The version of the Sezzle Checkout API the SDK will call. Use `v2` unless directed otherwise.
Available options: `v2`
### Sezzle Button
#### Sezzle Button Configuration
Place the element snippet from the Template tab where you wish the Sezzle Button to be rendered on the page, then update the Options attributes as needed.
```html theme={"system"}
```
```html theme={"system"}
```
Text to appear inside the button. Use `%%logo%%` inside the text to
display the Sezzle image
Available options: `square`, `semi-rounded`
Custom classes to be applied
Blank space between the top of the content and the top edge of the button
Blank space between the bottom of the content and the bottom edge of the button
Blank space between the left side of the content and the left edge of the button
Blank space between the right side of the content and the right edge of the button
Width of the Sezzle logo within the button
CSS `top` offset for the Sezzle logo inside the button (e.g., `2px`).
CSS `bottom` offset for the Sezzle logo inside the button (e.g., `2px`).
CSS `left` offset for the Sezzle logo inside the button (e.g., `2px`).
CSS `right` offset for the Sezzle logo inside the button (e.g., `2px`).
Spacing between the templateText letters.
Width of the button
Height of the button.
#### Render the Sezzle Button
Add the following function to render the button when it is appropriate, such as when payment methods section loads, or when Sezzle is selected as a payment method. The parameter corresponds to the element created in the previous step.
```javascript theme={"system"}
await checkoutSdk.renderSezzleButton("sezzle-smart-button-container");
```
### Initialize the Checkout
#### Event Handlers
The SDK uses these event handlers to tell your site what's happening in the checkout. Implement each one to react to shopper actions like completing, cancelling, or running into an error.
```javascript expandable theme={"system"}
checkoutSdk.init({
onClick: function () {
event.preventDefault();
checkoutSdk.startCheckout({...});
},
onComplete: function (response) {
console.log(response.data);
},
onCancel: function () {
alert("Transaction cancelled.");
},
onFailure: function () {
alert("Transaction failed.");
},
onCalculateAddressRelatedCosts: async function (
shippingAddress,
order_uuid
) {
// Authentication and the checkout update must run on your backend -
// the calls below hit Sezzle directly for illustration only.
// See the onCalculateAddressRelatedCosts section for the backend-safe pattern.
const response = await fetch(
"https://gateway.sezzle.com/v2/authentication",
{
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
public_key: string,
private_key: string,
}),
}
);
const data = await response.json();
const token = data.token;
const updateResponse = await fetch(
`https://gateway.sezzle.com/v2/order/{order_uuid}/checkout`,
{
method: "PATCH",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${token}`,
},
body: JSON.stringify({
currency_code: string,
address_uuid: shippingAddress.uuid,
shipping_options: [
{
name: string,
description: string,
shipping_amount_in_cents: integer,
tax_amount_in_cents: integer,
final_order_amount_in_cents: integer
}
]
}),
}
);
const updateStatus = updateResponse.ok;
return {
ok: updateStatus,
};
},
});
```
```javascript expandable theme={"system"}
checkoutSdk.init({
onClick: function () {
event.preventDefault();
checkoutSdk.startCheckout({
checkout_payload: {
// "cancel_url":{
// "href": "http://localhost:44300/demo/v2checkout.html"
// },
// "complete_url":{
// "href": "http://localhost:44300/demo/v2checkout.html"
// },
express_checkout_type: "multi-step",
order: {
intent: "AUTH",
reference_id: "543645yg5tg5675686",
description: "sezzle-store - #12749253509255",
requires_shipping_info: true,
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",
},
order_amount: {
amount_in_cents: 10000,
currency: "USD",
},
},
},
});
},
onComplete: function (response) {
alert("Completed transaction. Capture started.");
checkoutSdk
.capturePayment(response.data.order_uuid, {
capture_amount: {
amount_in_cents: 10000,
currency: "USD",
},
partial_capture: false,
})
.then((r) => {
console.log(r);
});
},
onCancel: function () {
alert("Transaction cancelled.");
},
onFailure: function () {
alert("Transaction failed.");
},
onCalculateAddressRelatedCosts: async function (
shippingAddress,
order_uuid
) {
// Authentication and the checkout update must run on your backend -
// the calls below hit Sezzle directly for illustration only.
// See the onCalculateAddressRelatedCosts section for the backend-safe pattern.
const response = await fetch(
"https://gateway.sezzle.com/v2/authentication",
{
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
private_key: "sz_pr_...",
public_key: "sz_pub_..."
}),
}
);
const data = await response.json();
const token = data.token;
const updateResponse = await fetch(
`https://gateway.sezzle.com/v2/order/{order_uuid}/checkout`,
{
method: "PATCH",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${token}`,
},
body: JSON.stringify({
currency_code: "USD",
address_uuid: shippingAddress.uuid,
shipping_options: [
{
name: "Standard Shipping",
description: "3-5 business days",
shipping_amount_in_cents: 2000,
tax_amount_in_cents: 3000,
final_order_amount_in_cents: 10200
},
{
name: "Express Shipping",
description: "1-2 business days",
shipping_amount_in_cents: 2000,
tax_amount_in_cents: 3000,
final_order_amount_in_cents: 10200
}
]
}),
}
);
const updateStatus = updateResponse.ok;
return {
ok: updateStatus,
};
},
});
```
Runs when the shopper clicks the Sezzle button.
Use this function to create the Sezzle checkout session and direct the shopper into that flow.
See [Checkout Initialization](#checkout-initialization) section for `startCheckout` payload options.
Runs when Sezzle checkout completes successfully. Use this to save the order and, if you used `intent: AUTH`, to capture the payment.
* See [Get Order Details](/docs/api/core/orders/getv2order) section to retrieve selected shipping method and other details such as shipping or billing address as needed.
* See [Capture Payment](#capture-payment) section for `capturePayment` payload options.
The checkout completion response
Checkout completion data
`"success"`
Checkout UUID
Session UUID
Order UUID
Origin URL of the checkout window
Runs when the shopper exits Sezzle checkout before completing payment. Use this to update the order status in your system.
The cancel event response
Cancel event data
`"cancel"`
The UUID of the checkout that failed
Session UUID
Order UUID
Origin URL of the checkout window
Runs when Sezzle checkout fails to load or hits an error. Use this to update the order status and surface the failure to the shopper.
The failure response
Error object or API error response. When `data` is an `Error`:
`"failure"`
The UUID of the checkout that failed
Session UUID
Order UUID
Error message (e.g., `"Public Key is missing."`)
Origin URL of the checkout window
Required if `express_checkout_type` is `single-step` or `multi-step`. Once shopper has provided shipping address via Sezzle express checkout, this callback function must be used to return tax and shipping costs to Sezzle. The merchant can also save the shipping address to their order management system at this time, or [get order details](/docs/api/core/orders/getv2order) from Sezzle during the onComplete callback.
See [onCalculateAddressRelatedCosts](#oncalculateaddressrelatedcosts) section for implementation details.
The shipping address provided by the shopper
The customer's first name
The customer's last name
The customer's phone number
The street and number of the address
The apt or unit
The city
The 2 character state code
The postal delivery code
The 2 character country code
The unique identifier for the address
The unique identifier for the order
#### Checkout Initialization
```javascript expandable theme={"system"}
checkoutSdk.startCheckout({
checkout_payload: {
// "cancel_url":{
// "href": string
// },
// "complete_url":{
// "href": string
// },
express_checkout_type: string,
order: {
intent: string,
reference_id: string,
description: string,
requires_shipping_info: boolean,
items: [
{
name: string,
sku: string,
quantity: integer,
price: {
amount_in_cents: integer,
currency: string,
},
},
],
discounts: [
{
name: string,
amount: {
amount_in_cents: integer,
currency: string,
},
},
],
metadata: {
some_property: string,
some_other_property: string
},
order_amount: {
amount_in_cents: integer,
currency: string,
},
},
},
});
```
```javascript theme={"system"}
checkoutSdk.startCheckout({
checkout_payload: {
// "cancel_url":{
// "href": "http://localhost:44300/demo/v2checkout.html"
// },
// "complete_url":{
// "href": "http://localhost:44300/demo/v2checkout.html"
// },
express_checkout_type: "multi-step",
order: {
intent: "AUTH",
reference_id: "543645yg5tg5675686",
description: "sezzle-store - #12749253509255",
requires_shipping_info: true,
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",
},
order_amount: {
amount_in_cents: 10000,
currency: "USD",
},
},
},
});
```
The `checkout_payload` schema mirrors the [Create Session](/docs/api/core/sessions/postv2session) request body. See that reference document for the full list of fields, types, and constraints - including `express_checkout_type` and `order.requires_shipping_info`.
The `startCheckout` method should be implemented in the checkout `onClick` handler. There are two ways to start checkout:
* **With a checkout payload** — pass the full session object inline (shown above). The cancel and complete URLs are optional for `iframe` and `popup` mode.
* **With an existing checkout URL** — call `startCheckout({ checkout_url, order_uuid })`. The SDK `mode` must match the `checkout_mode` you used when [creating the session](/docs/api/core/sessions/postv2session). For `iframe` and `popup`, include the parent window's `origin` in the cancel and complete URLs.
**Customer Tokenization:** the customer UUID isn't delivered through `onComplete`. To receive it, subscribe to the [customer.tokenized](/docs/api/core/webhooks/postv2webhooks#valid-webhook-events) webhook event.
#### Capture Payment
Skip this step if you used `CAPTURE` intent when starting the checkout — Sezzle captures the order automatically.
```javascript theme={"system"}
checkoutSdk
.capturePayment(response.data.order_uuid, {
capture_amount: {
amount_in_cents: integer,
currency: string,
},
partial_capture: boolean,
})
.then((r) => {
console.log(r);
});
```
```javascript theme={"system"}
checkoutSdk
.capturePayment(response.data.order_uuid, {
capture_amount: {
amount_in_cents: 10000,
currency: "USD",
},
partial_capture: false,
})
.then((r) => {
console.log(r);
});
```
The `capturePayment` request body mirrors the [Capture by Order](/docs/api/core/orders/postv2capturebyorder) request body. See that reference document for the full list of fields, types, and constraints.
#### onCalculateAddressRelatedCosts
For security purposes, authentication and checkout update must originate
from merchant's back-end code.
1. Get authentication token
* Call the [authentication](/docs/api/core/authentication/postauthentication) endpoint to obtain a bearer token
* You should have already set this up in your back-end for the standard integration
* Instead of pointing directly to Sezzle as in the below example, you can re-use your existing function
2. Update the order
* Call the [Update Checkout](/docs/api/core/orders/patchv2updatecheckoutbyorder) endpoint to provide Sezzle with shipping option(s) and final tax and shipping amount based on shopper's shipping address
Your back-end must respond within 40 seconds. If Sezzle does not receive your shipping option(s) within this window, the checkout fails with a `merchant_shipping_cost_timeout` error and the shopper is unable to complete their purchase.
Once `shipping_options` have been provided to Sezzle for a checkout, they cannot be edited unless the shopper changes their shipping address.
```javascript expandable theme={"system"}
onCalculateAddressRelatedCosts: async function (
shippingAddress,
order_uuid
) {
// Call authentication endpoint
const response = await fetch(
yourBackendAuthenticationURL,
{
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
public_key: string,
private_key: string,
}),
}
);
const data = await response.json();
const token = data.token;
const updateResponse = await fetch(
yourBackendUpdateOrderURL,
{
method: "PATCH",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${token}`,
},
body: JSON.stringify({
currency_code: string,
address_uuid: shippingAddress.uuid,
shipping_options: [
{
name: string,
description: string,
shipping_amount_in_cents: integer,
tax_amount_in_cents: integer,
final_order_amount_in_cents: integer
}
]
}),
}
);
const updateStatus = updateResponse.ok;
return {
ok: updateStatus,
};
},
```
```javascript expandable theme={"system"}
onCalculateAddressRelatedCosts: async function (
shippingAddress,
order_uuid
) {
// All this must be done inside your backend endpoint and this should be replaced with your endpoint communication logic
// Call authentication endpoint
const response = await fetch(
`https://sandbox.gateway.sezzle.com/v2/authentication`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
private_key: "sz_pr_...",
public_key: "sz_pub_..."
}),
}
);
const data = await response.json();
const token = data.token;
// Calculate your shipping options based on the provided shippingAddress
const shipping_options = [
{
name: "Standard Shipping",
description: "3-5 business days",
shipping_amount_in_cents: 1000,
tax_amount_in_cents: 500,
final_order_amount_in_cents: 11500
},
{
name: "Express Shipping",
description: "1-2 business days",
shipping_amount_in_cents: 2000,
tax_amount_in_cents: 1000,
final_order_amount_in_cents: 13000
}
]
// Update your checkout with the calculated shipping options
const updateResponse = await fetch(
`https://sandbox.gateway.sezzle.com/v2/order/{order_uuid}/checkout`,
{
method: "PATCH",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${token}`,
},
body: JSON.stringify({
currency_code: "USD",
address_uuid: shippingAddress.uuid,
shipping_options,
}),
}
);
const updateStatus = updateResponse.ok;
return {
ok: updateStatus,
};
}
```
The update request body mirrors the [Update Checkout by Order](/docs/api/core/orders/patchv2updatecheckoutbyorder) request body. See that reference document for the full list of fields, types, and constraints.
Express-specific behavior for `shipping_options`:
* If `express_checkout_type` is `multi-step` but only one method is provided, user experience will follow `single-step` flow from this point
* If `express_checkout_type` is `single-step` but multiple methods are provided, the shopper will be presented with an error.
* If `express_checkout_type` is `multi-step` or `single-step` and no methods are provided, the shopper will be asked to review their shipping address and try again.
##### Response
```json theme={"system"}
{
ok: boolean,
error: {
code: string
}
}
```
```json theme={"system"}
{
ok: false,
error: {
code: "merchant_unsupported_shipping_address"
}
}
```
Set to `true` once the shipping options have been successfully written to Sezzle, or `false` if the merchant rejects the address (return an `error.code` alongside).
Available options: `merchant_unsupported_shipping_address`, `merchant_error`
`merchant_unsupported_shipping_address` indicates that the merchant does not support the shipping address provided.
`merchant_error` is generic error returned by the merchant when something goes wrong on their end.