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

popup mode will work out-of-the-box. No additional configuration is required to use popup. Sezzle currently recommends popup mode. 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. The integration for popup and iframe are identical, aside from the mode. Using popup mode will expedite your development. Upon completing the integration, if iframe is a requirement, then contact Sezzle to enable your domain(s) and switch the mode to iframe.

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 (event) {
    console.log(event.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: "[email protected]",
                    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 (event) {
    console.log(event.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: "[email protected]",
        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

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": "1234",
        "cvv": "123",
        "expiryMonth": "02",
        "expiryYear": "28"
    },
    "holder": {
        "email": "[email protected]",
        "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

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.

Checkout initialization

checkout.init({
    onClick: function () {
        event.preventDefault();
        checkout.startCheckout({
            checkout_payload: {
                ...
+               "card_response_format":"token"
            }
        });
    },
    onComplete: function (event) {
        console.log(event.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,
});

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

Using API

The Update Card Session API endpoint exists where you are able to update the Order ID based.

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