Introduction

The Sezzle Virtual Card is intended for merchants interested in accepting Sezzle in the form of a credit card. This allows merchants to process Sezzle using their existing credit card form in the checkout.

If you have any questions regarding our API, please reach out to our team here: Submit Merchant Help Request

You should have an approved Sezzle account to start the integration process. Please visit our signup page if you don't have a Sezzle account already.

The endpoints in this guide also require an authentication token.

Card Session

A card session represents the issuance of a Sezzle virtual card to a Sezzle user and/or the agreement of a Sezzle user to use the virtual card as payment. Use the card session endpoints to create and update a card session.

Create a card session

POST https://gateway.sezzle.com/v2/session/card

You can use this endpoint to create a virtual card session. The response will include a session uuid and the Sezzle customer dashboard URL to be hosted in an iframe or popup.

Request Body

{
    "origin": "https://example.com",
    "mode": "iframe",
    "merchant_reference_id": "merchant-cart-id-max-255",
    "amount_in_cents": 1000,
    "currency": "USD",
    "customer": {
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "6125551234",
        "billing_address": {
            "street": "123 W Lake St",
            "street2": "Unit 104",
            "city": "Minneapolis",
            "state": "MN",
            "postal_code": "55408",
            "country_code": "US"
        }
    },
    "items": [
    {
      "name": "Blue tee",
      "sku": "sku123456",
      "quantity": 1,
      "price": {
        "amount_in_cents": 1000,
        "currency": "USD"
      }
    }
  ]
}

Response Body

{
  "uuid": "fadbc642-05a4-4e38-9e74-80e325623af9",
  "dashboard_url": "https://dashboard.sezzle.com/example?id=0001"
}

Card Session Object

Parameter	Type	Description
origin*	string	The window origin of the host
mode*	string	`iframe`\|`popup`
merchant_reference_id	string	The merchant reference id, typically checkout or cart id
amount_in_cents	int	The amount of the order in cents
currency	string	The 3 character currency code as defined by ISO 4217
customer	object	The customer for this session
card_response_format	string	Optional `token`. This determines the format of card data sent by window messaging on the front end. The default format is clear text.

Customer object

Parameter	Type	Description
email	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	object	The customer's billing address

Address Object

Parameter	Type	Description
street	string	The street and number of the address
street2	string	The apt or unit
city	string	The city
state	string	The 2 character state code
postal_code	string	The postal delivery code
country_code	string	The 2 character country code

Item Object

Parameter	Type	Description
name	string	The name of the item
sku	string	The sku identifier
quantity	int	The quantity purchased
price	object	The price object

Price Object

Parameter	Type	Description
amount_in_cents	int	The amount of the item in cents
currency	string	The 3 character currency code as defined by ISO 4217

Get card data by token

GET https://gateway.sezzle.com/v2/session/card/token/{token}

You can use this endpoint to request card data with the checkout card token. The card token is temporary and only available for a limited time. This endpoint is only needed when a card session is created with a card response format of token.

Response Body

{
  "cvv_number": "string",
  "expiration_date": "MMYY",
  "first_name": "string",
  "last_name": "string",
  "pan": "string"
}

Update a card session

PATCH https://gateway.sezzle.com/v2/session/{session_uuid}/card

You can use this endpoint to update the card session with your order ID. Once the virtual card transaction is completed and a Sezzle order is created, this order ID will be assigned to the (external) reference ID of the Sezzle order.

Request Body

{
  "order_id": "merchant_order_number"
}

Update Order Object

Parameter	Type	Description
order_id*	string	Your order ID (or number)

There is no response body for this request. If successful, we return an HTTP 204 Status No Content.

Virtual Card SDK

The Virtual Card SDK implements the Card Session API to provide an easy to use, in-context solution for issuing and using a Sezzle virtual card as payment.

Features

Get Installment Plan
Virtual Card Checkout in an iframe or pop-up window
Handle Virtual Card Approval Success
Handle Virtual Card Approval Cancel
Handle Virtual Card Approval Failure
Render Sezzle Button

Include the SDK

Include https://checkout-sdk.sezzle.com/checkout.min.js in the <head> section of the page.

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

Implement the SDK

Button Configuration

Button Placeholder

<div id="sezzle-smart-button-container"></div>

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

Button Customization

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

Use HTML attributes to customize the button.

Attribute	Description
templateText	Text that will prepended with the Sezzle logo. Default is `Checkout with %%logo%%`
borderType	Options are `square` and `semi-rounded`
customClass	Custom classes to be applied
paddingTop	Default is `1px`
paddingBottom	Default is `7px`
paddingLeft	Default is `30px`
paddingRight	Default is `30px`
sezzleImageWidth	Default is `84px`
sezzleImagePositionTop	Position of the Sezzle logo from top.
sezzleImagePositionBottom	Position of the Sezzle logo from bottom.
sezzleImagePositionLeft	Position of the Sezzle logo from left.
sezzleImagePositionRight	Position of the Sezzle logo from right.
letterSpacing	Spacing between the templateText letter.
width	Width of the button
height	Height of the button. Default is `4.2em`

Checkout Configuration

const checkout = new Checkout({
    'mode': "iframe|popup",
    'publicKey': "xxxx",
    'apiMode': "sandbox|live",
    'isVirtualCard': true
});

Edit the page file to implement the SDK.
Configure the SDK with the following options:

Attribute	Options
mode	`iframe`\|`popup`
apiMode	`sandbox`\|`live`
isVirtualCard	`true`
publicKey*	`xxxx` (used only when creating a checkout)

For security reasons, Sezzle must enable hosting a Sezzle virtual card checkout for merchants. To have it enabled, please send your Sezzle Merchant ID and a list of domains to be allowed per environment (production and sandbox) to our Merchant Support team.

Render the Sezzle Button

checkout.renderSezzleButton("sezzle-smart-button-container");

Call renderSezzleButton passing the id of the placeholder element defined in Button Configuration, above.

Initialize the Checkout

checkout.init({
    onClick: function () {
        event.preventDefault();
        checkout.startCheckout({
            checkout_payload: {
                amount_in_cents: 100,
                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 canceled");
    },
    onFailure: function() {
        console.log("checkout failed");
    }
})

The SDK requires the following event handlers:

Event	Description
onClick*	Sezzle Button is clicked by the user
onComplete*	Sezzle Virtual Card is successfully approved
onCancel*	Sezzle Virtual Card approval process is cancelled
onFailure*	Sezzle Virtual Card is not approved

Hosting the Checkout

To be implemented in the onClick handler. checkout_payload is optional, however, providing as much information as possible will improve the user experience. Note, the checkout_payload should be the request body of a create card session.

Checkout Events

A successfully completed Sezzle checkout will trigger an event to the onComplete handler. The event should include a data object with the session_id and objects with card and holder details.
If the user exits the Sezzle checkout for any reason, the onCancel handler will be executed.
If there is an error loading the Sezzle checkout page, the onFailure handler will be executed.

Completed Checkout Data

{
    "session_id": "example-sezzle-id",
    "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"
    }
}

The above completed checkout data is in clear text. If you choose to use a card response format of token, then the card object will instead include a token that can be used to request card data.

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

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

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

Get Installment Plan

This function will provide you the installment details based on the amount passed.

const checkoutSdk = new Checkout({});
checkoutSdk.getInstallmentPlan(100);

Get Installment Plan Response

{
    "schedule": "bi-weekly",
    "totalInCents": 100,
    "installments": [
        {
            "installment": 1,
            "amountInCents": 25,
            "dueDate": "2020-10-14"
        },
        {
            "installment": 2,
            "amountInCents": 25,
            "dueDate": "2020-10-28"
        },
        {
            "installment": 3,
            "amountInCents": 25,
            "dueDate": "2020-11-11"
        },
        {
            "installment": 4,
            "amountInCents": 25,
            "dueDate": "2020-11-25"
        }
    ]
}

Manual Integration

If the Virtual Card SDK is not a viable option, the manual integration will guide you through the steps to complete a virtual card session in your checkout.

Overview

window.addEventListener('message', function() {
    var data = event.data || Object.create(null);

    if (data.szl_source !== 'v_card') {
        console.log('invalid source');
        return;
    }

    var card = data.card;
    var holder = data.holder
    if (!card && !holder) {
        console.log('failed virtual card session');
        return;
    }

    console.log('card data:',
        card.firstName,
        card.lastName, 
        card.pan,
        card.cvv,
        card.expiryMonth,
        card.expiryYear);

    console.log('holder data:',
        holder.email,
        holder.phone,
        holder.firstName,
        holder.lastName,
        holder.address1,
        holder.address2,
        holder.city,
        holder.state,
        holder.country,
        holder.postalCode);
});

Create a virtual card session.
Add a window event listener with type message to the checkout page.
Open the card session dashboard_url using the mode provided in the create card session request.
Sezzle will post a message to the listener when the user has completed the card session.
Verify message event.data exists.
Verify event.data.szl_source is equal to v_card.
Verify event.data.card and event.data.holder both exist.

If exists, use card and holder data to submit the order by credit card
If not, the user did not provide virtual card data

(Optional) Upon order creation, use the card session uuid and the order ID to update the card session.