> ## 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** mode will work out-of-the-box, and Sezzle recommends it for most browser-based SDK integrations.
If your checkout runs inside a webview or embedded browser where popups may be blocked, use **iframe** mode instead. **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*](http://www.mysite.com).
**redirect** mode is also supported, but it is generally less useful with the SDK because the SDK's main value is handling the in-context checkout experience and window messaging between your site and Sezzle.
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
Create a placeholder element for the Sezzle Button to be rendered on the page(s).
```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
Negative space between top of content and edge of button
Negative space between bottom of content and edge of button
Negative space between left side of content and edge of button
Negative space between right side of content and edge of button
Width of the Sezzle logo within the button
Position of the Sezzle logo from top.
Position of the Sezzle logo from bottom.
Position of the Sezzle logo from left.
Position of the Sezzle logo from right.
Spacing between the templateText letter.
Width of the button
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.
```javascript theme={"system"}
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.
```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.");
},
});
```
Sezzle Button is clicked by the user.
See [Checkout Initialization](#checkout-initialization) section for payload options.
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.
Sezzle payment is cancelled. If the user exits the Sezzle checkout for any reason, the `onCancel` handler will be executed.
Sezzle payment has failed. If there is an error loading the Sezzle checkout page, the `onFailure` handler will be executed.
### 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 amount of the item in cents
The 3 character currency code as defined by ISO 4217
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](#set-order-reference-id)
The customer for the order
The customer's email address
The customer's first name
The customer's last name
The customer's phone number
The street and number of the address
The apt or unit
The city
The 2 character state code
The postal delivery code
The 2 character country code
The items being purchased
The name of the item
The sku identifier
The quantity purchased
The price object
The amount of the item in cents
The 3 character currency code as defined by ISO 4217
### `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"
}
}
```
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.
#### 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.