---
name: Sezzle
description: Use when building payment integrations for buy-now-pay-later (BNPL) checkout flows, implementing virtual card payments, managing orders and refunds, setting up webhooks for payment events, or integrating Sezzle into custom eCommerce platforms via API or SDK.
metadata:
    mintlify-proj: sezzle
    version: "1.0"
---

# Sezzle Skill

## Product Summary

Sezzle is a buy-now-pay-later (BNPL) payment platform that allows merchants to accept flexible installment payments. Agents use Sezzle to build payment integrations via REST API, JavaScript SDK, or pre-built platform plugins. Key entry points: authenticate with API keys at `POST /v2/authentication`, create payment sessions at `POST /v2/session`, manage orders with capture/refund/release operations, and subscribe to webhooks for payment events. Test in sandbox at `https://sandbox.dashboard.sezzle.com` before going live. Primary docs: https://docs.sezzle.com

## When to Use

Reach for this skill when:
- Building a direct API integration for custom checkout flows
- Implementing virtual card payments (card data delivered to your payment processor)
- Creating or managing orders (capture, refund, release, reauthorize, upcharge)
- Setting up webhooks to receive payment status updates
- Implementing customer tokenization for recurring charges
- Integrating Sezzle into a mobile app (iOS/Android SDK)
- Troubleshooting payment authorization, capture, or settlement issues
- Testing payment flows in sandbox before production deployment
- Implementing Express Checkout for faster shopper conversion

## Quick Reference

### Authentication
- Obtain bearer token: `POST /v2/authentication` with `public_key` and `private_key`
- Token expires in 120 minutes; obtain new tokens as needed
- Include token in all requests: `Authorization: Bearer {token}`
- API keys from: https://dashboard.sezzle.com/merchant/settings/apikeys (production) or https://sandbox.dashboard.sezzle.com/merchant/settings/apikeys (sandbox)

### Core API Endpoints

| Operation | Endpoint | Purpose |
|-----------|----------|---------|
| Create session | `POST /v2/session` | Initiate checkout with order details |
| Get session | `GET /v2/session/{uuid}` | Retrieve session and checkout URL |
| Get order | `GET /v2/order/{uuid}` | Fetch order status and details |
| Capture | `POST /v2/order/{uuid}/capture` | Capture authorized funds |
| Refund | `POST /v2/order/{uuid}/refund` | Refund captured amount |
| Release | `POST /v2/order/{uuid}/release` | Release authorized but uncaptured funds |
| Reauthorize | `POST /v2/order/{uuid}/reauthorize` | Reauthorize expired authorization |
| Upcharge | `POST /v2/order/{uuid}/upcharge` | Charge additional amount |
| Create webhook | `POST /v2/webhooks` | Subscribe to payment events |

### Webhook Events
- `order.authorized` — order authorized by Sezzle
- `order.captured` — funds captured
- `order.refunded` — refund processed
- `customer.tokenized` — customer approved for future charges
- `dispute.*` — dispute filed, deadline approaching, or closed

### Session Intent Options
- `AUTH` — authorize only; merchant must call capture later
- `CAPTURE` — authorize and capture immediately (recommended for most)

### Test Data (Sandbox Only)
- OTP: always `123123` (phone and email)
- Test credit cards: Visa `4242424242424242`, Mastercard `5555555555554444`, Amex `371449635398431`, Discover `6011111111111117` (any future expiry, any CVC)
- Test bank account (USD): routing `110000000`, account `000123456789`

### JavaScript SDK Configuration
```javascript
const checkout = new Checkout({
  mode: "popup",           // popup, iframe, or redirect
  publicKey: "sz_pub_...", // from dashboard
  apiMode: "sandbox",      // sandbox or live
  apiVersion: "v2"
});
```

## Decision Guidance

| Scenario | Use Direct API | Use JavaScript SDK | Use Platform Plugin |
|----------|---|---|---|
| Custom checkout flow | ✓ | ✓ | — |
| Shopify/WooCommerce/Magento | — | — | ✓ |
| Mobile app (iOS/Android) | — | — | ✓ (Mobile SDK) |
| Virtual card (credit card form) | ✓ | ✓ | — |
| Authorize-only workflow | ✓ | ✓ | ✓ |
| Recurring/tokenized charges | ✓ | — | — |
| Express Checkout (fast path) | ✓ | ✓ | ✓ (WooCommerce) |

| Payment Capture Strategy | When to Use |
|---|---|
| Authorize & Capture (default) | Most merchants; funds captured immediately after checkout |
| Authorize Only | Inventory validation needed, shipment-based charging, or regulatory requirements |

| Virtual Card Integration | When to Use |
|---|---|
| SDK (automated) | Fastest setup; SDK handles checkout UI and card delivery |
| Manual (postMessage) | Full control needed; you handle card data via browser postMessage (increases PCI scope) |

## Workflow

### 1. Direct API Integration (Standard Flow)

1. **Authenticate**: Call `POST /v2/authentication` with API keys; store bearer token (valid 120 min)
2. **Create session**: Call `POST /v2/session` with order object (amount, items, customer info, intent)
3. **Redirect**: Receive `checkout_url` from session response; redirect shopper to Sezzle checkout
4. **Shopper completes checkout**: Sezzle handles payment eligibility, installment selection, and approval
5. **Receive redirect**: Shopper redirected to your `complete_url` (or `cancel_url` if declined)
6. **Capture funds** (if intent was `AUTH`): Call `POST /v2/order/{uuid}/capture` with amount
7. **Subscribe to webhooks**: Call `POST /v2/webhooks` to receive `order.captured`, `order.refunded` events
8. **Manage order**: Use refund, release, reauthorize, or upcharge endpoints as needed

### 2. Virtual Card Integration (SDK)

1. **Initialize SDK**: Create `Checkout` object with `publicKey`, `mode`, `apiMode`
2. **Render button**: Call `checkoutSdk.renderSezzleButton()` or create custom button
3. **Handle click**: In `onClick` handler, call `checkoutSdk.startCheckout()` with card session payload
4. **Receive card data**: `onComplete` callback returns card number, CVV, holder info
5. **Process payment**: Send card data to your payment processor (Stripe, Cybersource, Braintree)
6. **Tokenize (optional)**: Use `card_response_format: "token"` to receive token instead of raw card data

### 3. Customer Tokenization (Recurring Charges)

1. **Create tokenize session**: Call `POST /v2/session` with `tokenize: true` and optional customer details
2. **Redirect to approval**: Shopper approves future charges at Sezzle checkout
3. **Receive customer UUID**: Via webhook (`customer.tokenized`), redirect parameter, or polling `GET /v2/token/{token}/session`
4. **Charge customer**: Call `POST /v2/customer/{customer_uuid}/order` to create orders without re-checkout
5. **Manage tokenized orders**: Use standard order endpoints (capture, refund, release)

### 4. Testing in Sandbox

1. **Create sandbox account**: Sign up at https://sandbox.dashboard.sezzle.com/merchant/signup
2. **Generate API keys**: Complete merchant application, then retrieve keys from Settings > API Keys
3. **Configure SDK/API**: Use sandbox API keys and `apiMode: "sandbox"`
4. **Use test data**: OTP `123123`, test credit cards, test bank account (see Quick Reference)
5. **Verify in dashboard**: View test orders at https://sandbox.dashboard.sezzle.com/merchant/orders
6. **Switch to production**: Update API keys and `apiMode: "live"` before going live

## Common Gotchas

- **Token expiration**: Tokens expire after 120 minutes. Implement token refresh logic; don't reuse expired tokens.
- **Environment mismatch**: Sandbox and production credentials are separate. Using sandbox keys in production (or vice versa) will fail. Verify dashboard URL and API keys match environment.
- **Authorization expiration**: Default auth expiration is 30 minutes (7 days for Shopify). If not captured before expiry, order is deleted. Extend via dashboard if needed.
- **Minimum order amount**: Orders must be ≥$35 (or configured minimum). Test with amounts in $20–$2500 range.
- **Virtual card PCI scope**: Manual virtual card integration (postMessage) puts your frontend in PCI DSS scope. Use SDK with `card_response_format: "token"` to reduce scope.
- **Tokenization approval URL expires in 30 minutes**: Create standalone tokenization sessions at the moment the customer clicks to authorize, not ahead of time.
- **Customer UUID not in onComplete**: For tokenization, subscribe to `customer.tokenized` webhook; the UUID is not returned in SDK `onComplete` callback.
- **Webhook subscription required for tokenization**: If using standalone tokenization, subscribe to `customer.tokenized` webhook before going live, or you won't be notified of approvals.
- **Partial capture/refund amounts**: When capturing or refunding, specify exact amount in cents. Partial operations are allowed but must not exceed authorized/captured amounts.
- **Order deletion on failed capture**: If auth expires without capture, the order is automatically deleted. No manual cleanup needed, but ensure capture logic is reliable.
- **Sandbox OTP always 123123**: In sandbox, OTP is hardcoded to `123123` for all users; real OTPs are never sent.
- **CSP allowlist for iframe mode**: If using `mode: "iframe"`, add `*.sezzle.com` to Content Security Policy allowlist.
- **Mobile SDK: never include private key**: Mobile apps must use only public key; private key must remain server-side for capture operations.

## Verification Checklist

Before submitting work:

- [ ] Authentication token obtained and included in all API requests
- [ ] Session created with correct intent (`AUTH` or `CAPTURE`) and order amount in cents
- [ ] Checkout URL received and shopper redirected successfully
- [ ] Complete URL and cancel URL are valid and reachable
- [ ] Order status verified in dashboard (authorized, captured, or refunded as expected)
- [ ] Webhook subscription created and endpoint is receiving events
- [ ] Capture called (if using `AUTH` intent) before authorization expires
- [ ] Refund/release/reauthorize operations tested with correct order UUID
- [ ] Test data used in sandbox (test cards, OTP `123123`, test bank account)
- [ ] API keys match environment (sandbox keys in sandbox, production keys in production)
- [ ] Error responses logged with `debug_uuid` for troubleshooting
- [ ] Tokenization flow tested if implementing recurring charges
- [ ] Virtual card data handled securely (tokenized or sent directly to payment processor, not stored)
- [ ] Mobile SDK initialized with public key only (private key server-side)
- [ ] CSP allowlist updated if using iframe mode

## Resources

- **Comprehensive page navigation**: https://docs.sezzle.com/llms.txt
- **API Reference**: https://docs.sezzle.com/docs/api/intro
- **Direct Integration Guide**: https://docs.sezzle.com/docs/guides/direct/introduction
- **Virtual Card Guide**: https://docs.sezzle.com/docs/guides/virtual/introduction
- **Tokenization Guide**: https://docs.sezzle.com/docs/api/tokenization/intro
- **Sandbox Testing**: https://docs.sezzle.com/docs/api/environments
- **Test Data**: https://docs.sezzle.com/docs/api/test-cards
- **Merchant Support**: https://merchant-help.sezzle.com/hc/en-us

---

> For additional documentation and navigation, see: https://docs.sezzle.com/llms.txt