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 <head> section of the page.

<script
    type="text/javascript"
    src="https://checkout-sdk.sezzle.com/express_checkout.min.js"
></script>

Checkout Configuration

Configuration Options

Template
Example
Options

const checkoutSdk = new Checkout({
  mode: string,
  publicKey: string,
  apiMode: string,
  apiVersion: string,
});

const checkoutSdk = new Checkout({
  mode: "popup",
  publicKey: "sz_pub_...",
  apiMode: "live",
  apiVersion: "v2",
});

string

default:"popup"

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, 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.

string

required

Used when creating a checkout or capturing payment. Find your API keys at https://dashboard.sezzle.com/merchant/settings/apikeys

string

default:"live"

Environment in which the checkout is to be completedAvailable options: live, sandbox

string

default:"v2"

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.

Template
Example
Options

<div
    id="sezzle-smart-button-container"
    style="text-align: center"
></div>

<div
    id="sezzle-smart-button-container"
    style="text-align: center"
    templateText="Pay with %%logo%%"
    borderType="semi-rounded"
    customClass="action,primary,checkout"
></div>

string

default:"Checkout with %%logo%%"

Text to appear inside the button. Use %%logo%% inside the text to display the Sezzle image

string

Available options: square, semi-rounded

string

Custom classes to be applied

string

default:"1px"

Blank space between the top of the content and the top edge of the button

string

default:"7px"

Blank space between the bottom of the content and the bottom edge of the button

string

default:"30px"

Blank space between the left side of the content and the left edge of the button

string

default:"30px"

Blank space between the right side of the content and the right edge of the button

string

default:"84px"

Width of the Sezzle logo within the button

string

CSS top offset for the Sezzle logo inside the button (e.g., 2px).

string

CSS bottom offset for the Sezzle logo inside the button (e.g., 2px).

string

CSS left offset for the Sezzle logo inside the button (e.g., 2px).

string

CSS right offset for the Sezzle logo inside the button (e.g., 2px).

string

Spacing between the templateText letters.

string

Width of the button

string

default:"4.2em"

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.

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.

Template
Example
Options

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,
    };
  },
});

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,
    };
  },
});

function

required

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 section for startCheckout payload options.

function

required

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 section to retrieve selected shipping method and other details such as shipping or billing address as needed.
See Capture Payment section for capturePayment payload options.

Show parameters

object

The checkout completion response

Show child attributes

object

Checkout completion data

Show child attributes

string

"success"

string

Checkout UUID

string

Session UUID

string

Order UUID

string

Origin URL of the checkout window

function

required

Runs when the shopper exits Sezzle checkout before completing payment. Use this to update the order status in your system.

Show parameters

object

The cancel event response

Show child attributes

object

Cancel event data

Show child attributes

string

"cancel"

string

The UUID of the checkout that failed

string

Session UUID

string

Order UUID

string

Origin URL of the checkout window

function

required

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.

Show parameters

object

The failure response

Show child attributes

object

Error object or API error response. When data is an Error:

Show child attributes

string

"failure"

string

The UUID of the checkout that failed

string

Session UUID

string

Order UUID

string

Error message (e.g., "Public Key is missing.")

string

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 from Sezzle during the onComplete callback.

See onCalculateAddressRelatedCosts section for implementation details.

Show parameters

object

The shipping address provided by the shopper

Show child attributes

string

The customer’s first name

string

The customer’s last name

string

The customer’s phone number

string

The street and number of the address

string

The apt or unit

string

The city

string

The 2 character state code

string

The postal delivery code

string

The 2 character country code

string

The unique identifier for the address

string

The unique identifier for the order

Checkout Initialization

Template
Example
Options

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,
      },
    },
  },
});

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 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. 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 webhook event.

Capture Payment

Skip this step if you used CAPTURE intent when starting the checkout — Sezzle captures the order automatically.

Template
Example
Options

checkoutSdk
  .capturePayment(response.data.order_uuid, {
    capture_amount: {
      amount_in_cents: integer,
      currency: string,
    },
    partial_capture: boolean,
  })
  .then((r) => {
    console.log(r);
  });

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 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.

Get authentication token
- Call the authentication 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
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

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.

Update Checkout only works while the checkout is open. Otherwise it returns 409. Don’t retry: return ok: false with the error code merchant_error from the callback so the shopper isn’t left waiting, and create a new session if they want to try again.The error message ends with the reason:

checkout-expired: the checkout has expired. By default this happens 30 minutes after the session is created, and Get Order returns the exact time as checkout_expiration.
checkout-authorized: the shopper has already completed checkout.
checkout-completion-in-progress: the shopper is completing checkout right now.

If Sezzle has already recorded the order as completed, you may get 422 with the message checkout already completed instead. Don’t retry this either.

Template
Example
Options

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,
  };
},

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 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

Template
Example
Options

{
  ok: boolean,
  error: {
    code: string
  }
}

{
  ok: false,
  error: {
    code: "merchant_unsupported_shipping_address"
  }
}

boolean

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).

object

Show child attributes

string

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.

Sezzle

Direct Integration

Virtual Card

Assets

Express Checkout

Mobile SDKs

Other

Installation

Include SDK code

Checkout Configuration

Configuration Options

Sezzle Button

Sezzle Button Configuration

Render the Sezzle Button

Initialize the Checkout

Event Handlers

Checkout Initialization

Capture Payment

onCalculateAddressRelatedCosts

Response

​Installation

​Include SDK code

​Checkout Configuration

​Configuration Options

​Sezzle Button

​Sezzle Button Configuration

​Render the Sezzle Button

​Initialize the Checkout

​Event Handlers

​Checkout Initialization

​Capture Payment

​onCalculateAddressRelatedCosts

Response

Installation

Include SDK code

Checkout Configuration

Configuration Options

Sezzle Button

Sezzle Button Configuration

Render the Sezzle Button

Initialize the Checkout

Event Handlers

Checkout Initialization

Capture Payment

onCalculateAddressRelatedCosts