Using Virtual Card SDK

This is the fastest way to get started using the virtual card offering from Sezzle. A virtual card checkout implements the Card Session API to provide an easy to use, in-context solution for issuing and using a Sezzle virtual card as payment.

The Sezzle non-production environment does not provide a way to test the payment processing using your provider.

The origin domain needs to be allowlisted by Sezzle for Virtual Card SDK to function. Please contact your Account Manager and they can do this for you.

Checkouts

Virtual Card Checkout in an iframe or pop-up window.

Card Details

Enable plain card details through message event or tokenization.

Payments

Handle payment success, failure, or cancel with your virtual card orders.

Sezzle Button

Render the Sezzle checkout button on your store.

Include SDK code

Include the following script in the <head> section of the page.

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

Checkout Configuration

The first requirement to get started with the Virtual Card SDK is to configure a new Checkout object.

Configuration Options

Template
Example
Options

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

const checkoutSdk = new Checkout({
  mode: "popup",
  publicKey: "sz_pub_...",
  apiMode: "sandbox",
  isVirtualCard: true,
});

mode

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.

publicKey

string

required

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

apiMode

string

default:"live"

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

isVirtualCard

boolean

Use true to enable this feature

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>

templateText

string

default:"Checkout with %%logo%%"

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

borderType

string

Available options: square, semi-rounded

customClass

string

Custom classes to be applied

paddingTop

string

default:"1px"

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

paddingBottom

string

default:"7px"

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

paddingLeft

string

default:"30px"

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

paddingRight

string

default:"30px"

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

sezzleImageWidth

string

default:"84px"

Width of the Sezzle logo within the button

sezzleImagePositionTop

string

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

sezzleImagePositionBottom

string

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

sezzleImagePositionLeft

string

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

sezzleImagePositionRight

string

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

letterSpacing

string

Spacing between the templateText letters.

width

string

Width of the button

height

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.

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 () {
    console.log("Checkout cancelled.");
  },
  onFailure: function () {
    console.log("Checkout failed.");
  },
});

checkoutSdk.init({
  onClick: function () {
    event.preventDefault();
    checkoutSdk.startCheckout({
            checkout_payload: {
                amount_in_cents: 1000,
                currency: "USD",
                merchant_reference_id: "merchant-checkout-id-max-255",
                customer: {
                    email: "test@test.com",
                    first_name: "John",
                    last_name: "Doe",
                    phone: "0987654321",
                    billing_address_street1: "3432 Terry Lane",
                    billing_address_street2: "12",
                    billing_address_city: "Katy",
                    billing_address_state: "TX",
                    billing_address_postal_code: "77449",
                    billing_address_country_code: "US",
                },
                items: [
                    {
                        name: "Blue tee",
                        sku: "sku123456",
                        quantity: 1,
                        price: {
                            amount_in_cents: 1000,
                            currency: "USD",
                        },
                    },
                ],
            },
    });
  },
onComplete: function (response) {
  // Virtual card data is available in response.data.card and response.data.holder.
  // Use this data to charge the card through your own payment processor
  // (e.g., Stripe, Cybersource, Braintree).
  console.log("Card data received:", response.data);
  },
  onCancel: function () {
    console.log("Checkout cancelled.");
  },
  onFailure: function () {
    console.log("Checkout failed.");
  },
});

onClick

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.

onComplete

function

required

Runs when Sezzle checkout completes successfully. Use this to save the order and payment details.

Response body depends upon the value of card_response_format provided in startCheckout.

For token (recommended), see onComplete with tokenization
Otherwise, see onComplete with card data

onCancel

function

required

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

Show parameters

response

object

The cancel event response

Show child attributes

data

object

Cancel event data

Show child attributes

status

string

"cancel"

checkout_uuid

string

The UUID of the checkout that failed

session_uuid

string

Session UUID

order_uuid

string

Order UUID

origin

string

Origin URL of the checkout window

onFailure

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

response

object

The failure response

Show child attributes

data

object

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

Show child attributes

status

string

"failure"

checkout_uuid

string

The UUID of the checkout that failed

session_uuid

string

Session UUID

order_uuid

string

Order UUID

message

string

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

origin

string

Origin URL of the checkout window

Checkout Initialization

Template
Example
Options

checkoutSdk.startCheckout({
  checkout_payload: {
    amount_in_cents: integer,
    currency: string,
    merchant_reference_id: string,
    customer: {
        email: string,
        first_name: string,
        last_name: string,
        phone: string,
        billing_address_street1: string,
        billing_address_street2: string,
        billing_address_city: string,
        billing_address_state: string,
        billing_address_postal_code: string,
        billing_address_country_code: string,
    },
    items: [
        {
            name: string,
            sku: string,
            quantity: integer,
            price: {
                amount_in_cents: integer,
                currency: string,
            },
        },
    ],
  },
});

checkoutSdk.startCheckout({
  checkout_payload: {
    amount_in_cents: 1000,
    currency: "USD",
    merchant_reference_id: "merchant-checkout-id-max-255",
    customer: {
        email: "test@test.com",
        first_name: "John",
        last_name: "Doe",
        phone: "0987654321",
        billing_address_street1: "3432 Terry Lane",
        billing_address_street2: "12",
        billing_address_city: "Katy",
        billing_address_state: "TX",
        billing_address_postal_code: "77449",
        billing_address_country_code: "US",
    },
    items: [
        {
            name: "Blue tee",
            sku: "sku123456",
            quantity: 1,
            price: {
                amount_in_cents: 1000,
                currency: "USD",
            },
        },
    ],
  },
});

checkout_payload is optional but providing as much information as possible will improve customer experience.

The checkout_payload schema mirrors the Create a card session request body. See that reference document for the full list of fields, types, and constraints - including card_response_format.

merchant_reference_id is used only for troubleshooting. The Reference ID that shows in the Merchant Dashboard can be set using Set Order Reference ID.

`onComplete` with card data

This response format delivers the full card number (PAN) and CVV directly to your frontend JavaScript. If your systems do not already handle raw cardholder data, this may expand your PCI DSS compliance scope. For a more secure alternative, see onComplete with tokenization, which keeps card data out of the browser and limits handling to your server.

The event.data will contain a fully formed payload containing the customers payment method. This information is not the payment method used to pay Sezzle but one that can be used through your payment gateway (Cybersource, Stripe, Braintree, etc).

`event.data` response

Template
Example
Options

{
    "session_id": string,
    "card": {
        "firstName": string,
        "lastName": string,
        "pan": string,
        "cvv": string,
        "expiryMonth": string,
        "expiryYear": string
    },
    "holder": {
        "email": string,
        "phone": string,
        "firstName": string,
        "lastName": string,
        "address1": string,
        "address2": string,
        "city": string,
        "state": string,
        "country": string,
        "postalCode": string
    }
}

{
    "session_id": "123",
    "card": {
        "firstName": "John",
        "lastName": "Doe",
        "pan": "4242424242424242",
        "cvv": "123",
        "expiryMonth": "02",
        "expiryYear": "28"
    },
    "holder": {
        "email": "john.doe@example.com",
        "phone": "6125551234",
        "firstName": "John",
        "lastName": "Doe",
        "address1": "123 W Lake St",
        "address2": "Unit 104",
        "city": "Minneapolis",
        "state": "MN",
        "country": "US",
        "postalCode": "55408"
    }
}

`onComplete` with tokenization

Recommended for most merchants. Tokenization keeps card data out of your browser and reduces your PCI DSS compliance scope. Card data is retrieved server-side only.

Tokenization is a feature developed for merchants who do not want the card information sent directly through the message event. Instead the payload to onComplete will contain a card token string, which your server can exchange for card data using the Virtual Card Data API. The token is single-use and expires after 24 hours.

Checkout initialization

checkout.init({
    onClick: function () {
        event.preventDefault();
        checkout.startCheckout({
            checkout_payload: {
                ...
+               "card_response_format":"token"
            }
        });
    },
    onComplete: function (response) {
      console.log(response.data);
    },
    onCancel: function() {
        console.log("checkout canceled");
    },
    onFailure: function() {
        console.log("checkout failed");
    }
})

`event.data` response

Template
Example
Options

{
    "card": {
        "token": string
    }
}

{
    "card": {
        "token": "abc12345"
    }
}

Get card data

The virtual card data can be obtained using the token above using the Virtual Card Data method.

Set Order Reference ID

In many cases, the merchant order ID will not be generated until after the checkout is completed and an order is created. Call setOrderReferenceID to set the Sezzle Order Reference ID with the merchant order ID after the virtual card transaction has been successfully completed.

Using SDK

Template
Example
Options

checkoutSdk.setOrderReferenceID({
    session_id: string,
    order_id: string,
});

checkoutSdk.setOrderReferenceID({
    session_id: "example-session-id",
    order_id: "merchant-order-id",
});

session_id

string

The unique identifier for the card session, returned in the onComplete event data

order_id

string

Your merchant order ID to associate with this Sezzle order

Using API

The Update Card Session API endpoint allows you to update the Order ID for a given card session.

Checkouts

Card Details

Payments

Sezzle Button

​Include SDK code

​Checkout Configuration

​Configuration Options

​Sezzle Button

​Sezzle Button Configuration

​Render the Sezzle Button

​Initialize the Checkout

​Event Handlers

​Checkout Initialization

​onComplete with card data

​event.data response

​onComplete with tokenization

​Checkout initialization

​event.data response

​Get card data

​Set Order Reference ID

​Using SDK

​Using API

Include SDK code

Checkout Configuration

Configuration Options

Sezzle Button

Sezzle Button Configuration

Render the Sezzle Button

Initialize the Checkout

Event Handlers

Checkout Initialization

`onComplete` with card data

`event.data` response

`onComplete` with tokenization

Checkout initialization

`event.data` response

Get card data

Set Order Reference ID

Using SDK

Using API