Sezzle Virtual Card SDK

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

ParameterTypeDescription
origin*stringThe window origin of the host
mode*stringiframe|popup
merchant_reference_idstringThe merchant reference id, typically checkout or cart id
amount_in_centsintThe amount of the order in cents
currencystringThe 3 character currency code as defined by ISO 4217
customerobjectThe customer for this session
card_response_formatstringOptional token. This determines the format of card data sent by window messaging on the front end. The default format is clear text.

Customer object

ParameterTypeDescription
emailstringThe customer's email address
first_namestringThe customer's first name
last_namestringThe customer's last name
phonestringThe customer's phone number
billing_addressobjectThe customer's billing address

Address Object

ParameterTypeDescription
streetstringThe street and number of the address
street2stringThe apt or unit
citystringThe city
statestringThe 2 character state code
postal_codestringThe postal delivery code
country_codestringThe 2 character country code

Item Object

ParameterTypeDescription
namestringThe name of the item
skustringThe sku identifier
quantityintThe quantity purchased
priceobjectThe price object

Price Object

ParameterTypeDescription
amount_in_centsintThe amount of the item in cents
currencystringThe 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

ParameterTypeDescription
order_id*stringYour 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.
AttributeDescription
templateTextText that will prepended with the Sezzle logo. Default is Checkout with %%logo%%
borderTypeOptions are square and semi-rounded
customClassCustom classes to be applied
paddingTopDefault is 1px
paddingBottomDefault is 7px
paddingLeftDefault is 30px
paddingRightDefault is 30px
sezzleImageWidthDefault is 84px
sezzleImagePositionTopPosition of the Sezzle logo from top.
sezzleImagePositionBottomPosition of the Sezzle logo from bottom.
sezzleImagePositionLeftPosition of the Sezzle logo from left.
sezzleImagePositionRightPosition of the Sezzle logo from right.
letterSpacingSpacing between the templateText letter.
widthWidth of the button
heightHeight 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:
AttributeOptions
modeiframe|popup
apiModesandbox|live
isVirtualCardtrue
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:

EventDescription
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);
});
  1. Create a virtual card session.
  2. Add a window event listener with type message to the checkout page.
  3. Open the card session dashboard_url using the mode provided in the create card session request.
  4. Sezzle will post a message to the listener when the user has completed the card session.
  5. Verify message event.data exists.
  6. Verify event.data.szl_source is equal to v_card.
  7. 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
  1. (Optional) Upon order creation, use the card session uuid and the order ID to update the card session.