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
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 |
---|---|---|
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 adata
object with thesession_id
and objects withcard
andholder
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 tov_card
. - Verify
event.data.card
andevent.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.
Updated 6 months ago