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

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

Create a placeholder element for the Sezzle Button to be rendered on the page(s).

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"

Negative space between top of content and edge of button

paddingBottom

string

default:"7px"

Negative space between bottom of content and edge of button

paddingLeft

string

default:"30px"

Negative space between left side of content and edge of button

paddingRight

string

default:"30px"

Negative space between right side of content and edge of button

sezzleImageWidth

string

default:"84px"

Width of the Sezzle logo within the button

sezzleImagePositionTop

string

Position of the Sezzle logo from top.

sezzleImagePositionBottom

string

Position of the Sezzle logo from bottom.

sezzleImagePositionLeft

string

Position of the Sezzle logo from left.

sezzleImagePositionRight

string

Position of the Sezzle logo from right.

letterSpacing

string

Spacing between the templateText letter.

width

string

Width of the button

height

string

default:"4.2em"

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.

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.

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

Sezzle Button is clicked by the user.

See Checkout Initialization section for payload options.

onComplete

function

required

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.

onCancel

function

required

Sezzle payment is cancelled. If the user exits the Sezzle checkout for any reason, the onCancel handler will be executed.

onFailure

function

required

Sezzle payment has failed. If there is an error loading the Sezzle checkout page, the onFailure handler will be executed.

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.

amount_in_cents

integer

The amount of the item in cents

currency

string

default:"USD"

The 3 character currency code as defined by ISO 4217

merchant_reference_id

string

Typically a checkout or cart id, currently used for tracking only (must contain only alphanumeric characters, dashes (-), and underscores (_))

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

customer

object

The customer for the order

Show child attributes

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

billing_address_street1

string

The street and number of the address

billing_address_street2

string

The apt or unit

billing_address_city

string

The city

billing_address_state

string

The 2 character state code

billing_address_postal_code

string

The postal delivery code

billing_address_country_code

string

The 2 character country code

items

array

The items being purchased

Show child attributes

name

string

The name of the item

sku

string

The sku identifier

quantity

integer

The quantity purchased

price

object

The price object

Show child attributes

amount_in_cents

integer

The amount of the item in cents

currency

string

default:"USD"

The 3 character currency code as defined by ISO 4217

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

Sezzle

Direct Integration

Virtual Card

Assets

Express Checkout

Other

Using Virtual Card SDK

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

Sezzle

Direct Integration

Virtual Card

Assets

Express Checkout

Other

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