> ## 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 is a powerful tool for custom platform merchants. Integrated directly into the cart page, the button allows shoppers to select Sezzle as their payment method with a single click, leveraging their Sezzle account for a seamless payment experience. This feature is designed to reduce cart abandonment, increase conversion rate, and enhance customer satisfaction.
## 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** mode will work out-of-the-box, and Sezzle recommends it for most browser-based SDK integrations.
If your checkout runs inside a webview or embedded browser where popups may be blocked, use **iframe** mode instead. **iframe** mode will not work properly without first contacting Sezzle. For security reasons, Sezzle must enable **iframe** for your domain(s). 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). For example, [*please enable uat1.mysite.com, uat2.mysite.com in sandbox and www.mysite.com, mysite.com in production*](http://www.mysite.com).
**redirect** mode is also supported, but it is generally less useful with the SDK because the SDK's main value is handling the in-context checkout experience and window messaging between your site and Sezzle.
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`
Sezzle Checkout SDK Version
Available options: `v2`
### Sezzle Button
#### Sezzle Button Configuration
Create a placeholder element for the Sezzle Button to be rendered on the page(s).
```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
Negative space between top of content and edge of button
Negative space between bottom of content and edge of button
Negative space between left side of content and edge of button
Negative space between right side of content and edge of button
Width of the Sezzle logo within the button
Position of the Sezzle logo from top.
Position of the Sezzle logo from bottom.
Position of the Sezzle logo from left.
Position of the Sezzle logo from right.
Spacing between the templateText letter.
Width of the button
Height of the button.
#### Render the Sezzle Button
Requires having the checkout object created from above to render the button. Call renderSezzleButton passing the id of the placeholder element defined in Button Configuration, above.
```javascript theme={"system"}
await checkoutSdk.renderSezzleButton("sezzle-smart-button-container");
```
### Initialize the Checkout
#### Event Handlers
The SDK requires the following event handlers that can be used to extend features in your application.
```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
) {
// Call authentication endpoint
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
) {
// Call authentication endpoint
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,
};
},
});
```
Sezzle Button is clicked by the user.
See [Checkout Initialization](#checkout-initialization) section for payload options.
Sezzle payment is successfully completed. A successfully completed Sezzle checkout will trigger an event to the `onComplete` handler. The event should include a data object with data relevant to the start checkout input parameter.
See [capturePayment](#capture-payment) section for payload options.
Sezzle payment is cancelled. If the user exits the Sezzle checkout for any reason, the `onCancel` handler will be executed.
Sezzle payment has failed. If there is an error loading the Sezzle checkout page, the `onFailure` handler will be executed.
Required if `express_checkout_type` is `single-step` or `multi-step`. Once shopper has provided shipping address via Sezzle express checkout, this function should return tax and shipping costs to Sezzle.
#### 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 HTTP request information used to redirect the customer in the case of a cancellation
The URL used when redirecting a customer
The HTTP request information used to redirect the customer upon completion of the session
The URL used when redirecting a customer
* `single-step`: only one shipping method exists, or only use default shipping method for Sezzle express checkout flow
* `multi-step`: allow the user to select from merchant-supported shipping methods
* `no-shipping`: purchase contains no shippable items and shopper does not have option to select, such as digital download or buy online pick up in store (BOPIS)
For `single-step and `multi-step`, `requires\_shipping\_info`must be`true`. For `no-shipping`, `requires\_shipping\_info`must be`false\`
Available options: `single-step`, `multi-step`, `no-shipping`
The order for this session
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”.
Available options: `AUTH`, `CAPTURE`
Your reference ID for this order (must contain only alphanumeric characters, dashes (-), and underscores (\_))
Your description for this order
Flag to indicate if you would like us to collect shipping information for this checkout from the customer. If omitted, defaults to false.
If `express_checkout_type` is `single-step` or `multi-step`, `requires_shipping_info` must be `true`. For `express_checkout_type`: `no-shipping` and standard checkout, use `false`
The items being purchased
The name of the item
The sku identifier
The quantity purchased
The price object
The amount of the item in cents
The 3 character currency code as defined by ISO 4217
The discounts applied to this order. Must be included in total
The description of the discount
A price object
The amount of the item in cents
The 3 character currency code as defined by ISO 4217
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
Custom metadata field
Custom metadata field
The taxes applied to this order. Must be included in the total. If `express_checkout_type` is `single-step` or `multi-step`, this can be omitted - it will be provided after shopper confirms shipping address.
The amount of the item in cents
The 3 character currency code as defined by ISO 4217
The total amount of the order
The amount of the item in cents
The 3 character currency code as defined by ISO 4217
Start checkout should be implemented in the checkout `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` and `popup` mode.
**Use an existing checkout URL**
* The `mode` used when configuring the SDK checkout must match the `checkout_mode` when [creating a session](/docs/api/core/sessions/postv2session).
* The parent window `origin` must be provided in the cancel and complete urls when the `checkout_mode` is `iframe` or `popup`.
**Customer Tokenization** This is not supported in the `onComplete` event.
To receive a customer UUID, subscribe to the
[customer.tokenized](/docs/api/core/webhooks/postv2webhooks#valid-webhook-events)
event.
#### Capture Payment
Capturing an order is not required if the `CAPTURE` intent was used when
creating the checkout.
```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 amount to capture on this order
The amount in cents
The 3 character currency code as defined by ISO 4217
#### 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 endpoint to provide Sezzle with shipping option(s) and final tax and shipping amount based on shopper's shipping address
* See `Options` tab below for more details
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 3 character currency code as defined by ISO 4217
The address UUID for the order
The available shipping options for the order, in order of recommendation/preference
* 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.
The name of the shipping method
The description of the shipping method, such as number of business days
The shipping amount in cents for the order
The tax amount in cents for the order
The final total amount in cents for the order
##### Response
```json theme={"system"}
{
ok: boolean,
error: {
code: string
}
}
```
```json theme={"system"}
{
ok: false,
error: {
code: "merchant_unsupported_shipping_address"
}
}
```
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.