> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sezzle.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
Virtual Card Checkout in an iframe or pop-up window.
Enable plain card details through message event or tokenization.
Handle payment success, failure, or cancel with your virtual card orders.
Render the Sezzle checkout button on your store.
## Include SDK code
Include the following script in the `` section of the page.
```html theme={"system"}
```
## Checkout Configuration
The first requirement to get started with the Virtual Card SDK is to configure a new Checkout object.
### Configuration Options
```javascript theme={"system"}
const checkoutSdk = new Checkout({
mode: string,
publicKey: string,
apiMode: string,
isVirtualCard: boolean,
});
```
```javascript theme={"system"}
const checkoutSdk = new Checkout({
mode: "popup",
publicKey: "sz_pub_...",
apiMode: "sandbox",
isVirtualCard: true,
});
```
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** (recommended): works out of the box for most browser-based SDK integrations.
* **iframe**: required when popups are blocked (e.g. inside a webview or embedded browser). Sezzle must enable iframe for your domain(s) first — submit your Merchant UUID and the domains to allow per environment (sandbox and production). For example: *please enable uat1.mysite.com, uat2.mysite.com in sandbox and [www.mysite.com](http://www.mysite.com), mysite.com in production*.
* **redirect**: supported but generally less useful with the SDK, since the SDK's value is the in-context checkout and window messaging.
Used when creating a checkout or capturing payment. Find your API keys at [https://dashboard.sezzle.com/merchant/settings/apikeys](https://dashboard.sezzle.com/merchant/settings/apikeys)
Environment in which the checkout is to be completed
Available options: `live`, `sandbox`
Use `true` to enable this feature
## Sezzle Button
### Sezzle Button Configuration
Place the element snippet from the Template tab where you wish the Sezzle Button to be rendered on the page, then update the Options attributes as needed.
```html theme={"system"}
```
```html theme={"system"}
```
Text to appear inside the button. Use `%%logo%%` inside the text to
display the Sezzle image
Available options: `square`, `semi-rounded`
Custom classes to be applied
Blank space between the top of the content and the top edge of the button
Blank space between the bottom of the content and the bottom edge of the button
Blank space between the left side of the content and the left edge of the button
Blank space between the right side of the content and the right edge of the button
Width of the Sezzle logo within the button
CSS `top` offset for the Sezzle logo inside the button (e.g., `2px`).
CSS `bottom` offset for the Sezzle logo inside the button (e.g., `2px`).
CSS `left` offset for the Sezzle logo inside the button (e.g., `2px`).
CSS `right` offset for the Sezzle logo inside the button (e.g., `2px`).
Spacing between the templateText letters.
Width of the button
Height of the button.
### Render the Sezzle Button
Add the following function to render the button when it is appropriate, such as when payment methods section loads, or when Sezzle is selected as a payment method. The parameter corresponds to the element created in the previous step.
```javascript theme={"system"}
checkoutSdk.renderSezzleButton("sezzle-smart-button-container");
```
## Initialize the Checkout
### Event Handlers
The SDK uses these event handlers to tell your site what's happening in the checkout. Implement each one to react to shopper actions like completing, cancelling, or running into an error.
```javascript theme={"system"}
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.");
},
});
```
```javascript expandable theme={"system"}
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.");
},
});
```
Runs when the shopper clicks the Sezzle button.
Use this function to create the Sezzle checkout session and direct the shopper into that flow.
See [Checkout Initialization](#checkout-initialization) section for `startCheckout` payload options.
Runs when Sezzle checkout completes successfully. Use this to save the order and payment details.
Response body depends upon the value of `card_response_format` provided in `startCheckout`.
* For `token` (recommended), see [onComplete with tokenization](#oncomplete-with-tokenization)
* Otherwise, see [onComplete with card data](#oncomplete-with-card-data)
Runs when the shopper exits Sezzle checkout before completing payment. Use this to update the order status in your system.
The cancel event response
Cancel event data
`"cancel"`
The UUID of the checkout that failed
Session UUID
Order UUID
Origin URL of the checkout window
Runs when Sezzle checkout fails to load or hits an error. Use this to update the order status and surface the failure to the shopper.
The failure response
Error object or API error response. When `data` is an `Error`:
`"failure"`
The UUID of the checkout that failed
Session UUID
Order UUID
Error message (e.g., `"Public Key is missing."`)
Origin URL of the checkout window
### Checkout Initialization
```javascript expandable theme={"system"}
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,
},
},
],
},
});
```
```javascript expandable theme={"system"}
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.
The `checkout_payload` schema mirrors the [Create a card session](/docs/api/core/sessions/virtual/postv2sessioncard) request body. See that reference document for the full list of fields, types, and constraints - including `card_response_format`.
`merchant_reference_id` is used only for troubleshooting. The Reference ID that shows in the Merchant Dashboard can be set using [Set Order Reference ID](#set-order-reference-id).
### `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](#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
```json expandable theme={"system"}
{
"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
}
}
```
```json expandable theme={"system"}
{
"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"
}
}
```
The unique identifier for this card session
The first name on the card
The last name on the card
The 16 digit card number
The security code on back of the card
The expiration month on the card
The expiration year on the card
The customer's email address
The customer's phone number
The customer's first name
The customer's last name
The street and number of the address
The apt or unit
The city
The 2 character state code
The 2 character country code
The postal delivery code
### `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](/docs/api/core/sessions/virtual/carddatabytoken) API. The token is single-use and expires after 24 hours.
#### Checkout initialization
```diff theme={"system"}
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
```json theme={"system"}
{
"card": {
"token": string
}
}
```
```json theme={"system"}
{
"card": {
"token": "abc12345"
}
}
```
The unique identifier for this card session
Single-use token for retrieving card data server-side via the [Virtual Card Data](/docs/api/core/sessions/virtual/carddatabytoken) API. Expires after 24 hours.
The customer's email address
The customer's phone number
The customer's first name
The customer's last name
The street and number of the address
The apt or unit
The city
The 2 character state code
The 2 character country code
The postal delivery code
#### Get card data
The virtual card data can be obtained using the token above using the [Virtual Card Data](/docs/api/core/sessions/virtual/carddatabytoken) 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
```javascript theme={"system"}
checkoutSdk.setOrderReferenceID({
session_id: string,
order_id: string,
});
```
```javascript theme={"system"}
checkoutSdk.setOrderReferenceID({
session_id: "example-session-id",
order_id: "merchant-order-id",
});
```
The unique identifier for the card session, returned in the `onComplete` event data
Your merchant order ID to associate with this Sezzle order
### Using API
The [Update Card Session](/docs/api/core/sessions/virtual/setorderid) API endpoint allows you to update the Order ID for a given card session.