# Get a bearer authentication token Source: https://docs.sezzle.com/docs/api/core/authentication/postauthentication post /v2/authentication Generate authentication token from your Sezzle merchant API keys for use in the header of all other API requests. # Get interest account activity Source: https://docs.sezzle.com/docs/api/core/interest/getv2activity get /v2/interest/activity If you are enrolled in the interest account program, get the current activity on the interest account. # Get interest account balance Source: https://docs.sezzle.com/docs/api/core/interest/getv2balance get /v2/interest/balance If you are enrolled in the interest account program, get the current balance on the interest account. Fractions of cents are tracked to properly calculate daily interest accrual even if the interest balance is low. # Get order reports Source: https://docs.sezzle.com/docs/api/core/orderreports/getv2orderreports get /v2/orders/report Get a detailed list of orders across all order types within a date range. This endpoint is available by request only. Contact Sezzle to have your merchant account whitelisted before using it. The maximum reportable date range is **7 days**. `end-date` must be on or after `start-date` and no more than 7 days after it. **Sample request** ``` GET https://gateway.sezzle.com/v2/orders/report?start-date=2026-05-08&end-date=2026-05-08 ``` # Delete checkout by order Source: https://docs.sezzle.com/docs/api/core/orders/deletev2deletecheckoutbyorder delete /v2/order/{order_uuid}/checkout Delete an active (incomplete) checkout for an order. An example use-case is when a customer has been redirected to Sezzle but the order is cancelled in the ecommerce platform, call this endpoint to prevent the customer from completing the Sezzle checkout. # Get order details Source: https://docs.sezzle.com/docs/api/core/orders/getv2order get /v2/order/{order_uuid} Get details and check the status of an existing order.\ Can be performed any time after session creation # Payment Flow Source: https://docs.sezzle.com/docs/api/core/orders/index Group2 Pn

1. Merchant calls `/v2/session` with order and intent of `AUTH` or `CAPTURE`. Optionally, the merchant can send customer information 2. Sezzle returns order uuid and checkout URL. 3. Merchant redirects customer to Sezzle checkout URL. 4. Customer completes the Sezzle checkout and is redirected to the session complete URL. * If the intent was to `CAPTURE`, Sezzle will capture the total order amount. * If the intent was to `AUTH`, Sezzle will only authorize the total order amount and the merchant can call `/v2/order` later to release or capture amounts using the order uuid. ## Supported Methods # Update order Source: https://docs.sezzle.com/docs/api/core/orders/patchv2checkout patch /v2/order/{order_uuid} Once transaction is completed, update Sezzle order with merchant reference ID # Update checkout by order Source: https://docs.sezzle.com/docs/api/core/orders/patchv2updatecheckoutbyorder patch /v2/order/{order_uuid}/checkout Complete an Express Checkout order This endpoint should be used with our express checkout offering. It is not intended for the direct integration flow. # Capture amount by order Source: https://docs.sezzle.com/docs/api/core/orders/postv2capturebyorder post /v2/order/{order_uuid}/capture Capture an amount by order, either in full or partial capture, in cases when the order items are shipped separately.\ Can be performed after shopper has authorized the transaction by completing checkout with Sezzle, but before authorization expires # Reauthorize amount by order Source: https://docs.sezzle.com/docs/api/core/orders/postv2reauthorizebyorder post /v2/order/{order_uuid}/reauthorize Reauthorize an amount by order whose initial authorization has expired before payment could be captured. Any attempts to reauthorize before the authorization expires will fail.\ Can be performed after shopper has authorized the transaction by completing checkout with Sezzle Please note the following when reauthorizing an order. * A new order will be created * The intent will be set to AUTH * The reference\_id will be the same as the original order * The reauthorized amount will be a new installment plan for the customer Reauthorizations are not guaranteed to be approved. It is extremely important to note this API will return a 200 success if the request to reauthorize is successful (i.e. no errors) but the customer was not approved. Please be sure to check the authorization **approved** value in the response to determine if the reauthorization order was created. # Refund amount by order Source: https://docs.sezzle.com/docs/api/core/orders/postv2refundbyorder post /v2/order/{order_uuid}/refund Refund an amount by order. An example use-case is when an order was captured but the customer returned item(s) that requires them to be refunded.\ Can be performed after order capture. # Release amount by order Source: https://docs.sezzle.com/docs/api/core/orders/postv2releasebyorder post /v2/order/{order_uuid}/release Release an amount by order. An example use-case is when an order is unable to be fully fulfilled and part of the authorization needs to be released. Then a capture can be called for the remaining amount.\ Can be performed after shopper has authorized the transaction by completing checkout with Sezzle but before the payment is fully captured. # Upcharge amount by order Source: https://docs.sezzle.com/docs/api/core/orders/postv2upchargebyorder post /v2/order/{order_uuid}/upcharge Use this endpoint to upcharge an amount on an existing order. Can be performed after payment authorization. Upon success, a new separate order is created for the upcharge amount only. The original order is not released and remains in its current state. The upcharge amount is charged to the shopper as a single payment. The cumulative total of all upcharges on a given order must not exceed 15% of the original order amount. The currency of the upcharge must match the currency of the original order. The relationship between the upcharge order and the original order is queryable via Get Order: the upcharge order returns `is_upcharge: true` and `parent_order_uuid`, and the original order returns an `upcharges` array listing each upcharge. This API is in development and not yet available for production use. Details on this page are subject to change. ## Overview The upcharge endpoint allows you to charge an additional amount on an existing authorized order. This is useful when the final order total exceeds the originally authorized amount (e.g., due to weight-based pricing adjustments, added services, or shipping cost changes). ### Key behavior * A **new, separate order** is created for the upcharge amount only. The original order is **not** released or modified. * The upcharge amount is charged to the shopper as a **single payment** (Pay In Full). * The **cumulative total** of all upcharges on a given order must not exceed **15%** of the original authorized amount. * The upcharge currency **must match** the original order's currency. * The returned UUID is the new upcharge order's UUID and can be used with other Order API endpoints (e.g., capture, refund). * The two orders remain associated -- you can query the relationship via the [Get Order](/api/core/orders/getv2order) endpoint: * On the **upcharge order**, the response includes `is_upcharge: true` and `parent_order_uuid` referencing the original order. * On the **original order**, the response includes an `upcharges` array listing each upcharge order's UUID and amount. ### Validation requirements * The original order must have an approved authorization. * `intent` must be either `AUTH` or `CAPTURE`. * `upcharge_amount` must include a valid `amount_in_cents` and `currency`. ### Example For an original order of 100.00 USD: * Maximum cumulative upcharge allowed: **15.00 USD** (15% of 100.00) * A single upcharge of 10.00 succeeds, leaving 5.00 of remaining upcharge capacity. * A subsequent upcharge of 6.00 would be rejected (cumulative 16.00 exceeds the 15% limit). # Get session status Source: https://docs.sezzle.com/docs/api/core/sessions/getv2session get /v2/session/{session_uuid} Get session details # Create a session Source: https://docs.sezzle.com/docs/api/core/sessions/postv2session post /v2/session Initiate a Sezzle session with shopper order details, redirect links, and capture and tokenization settings # Get card data by token Source: https://docs.sezzle.com/docs/api/core/sessions/virtual/carddatabytoken get /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. **Security Rules** Data is only available for 24 hours and requires an authorization token. Once accessed the token is deleted which cannot be undone. # Create a card session Source: https://docs.sezzle.com/docs/api/core/sessions/virtual/postv2sessioncard post /v2/session/card Creates a Sezzle virtual 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. This endpoint should be used with our virtual card offering. It is not intended for the direct integration flow. # Update a card session Source: https://docs.sezzle.com/docs/api/core/sessions/virtual/setorderid patch /v2/session/{session_id}/card After the virtual card transaction for this session is successfully completed and a Sezzle order is created, call this endpoint to assign your order ID to the (external) reference ID of the Sezzle order. # Get summary Source: https://docs.sezzle.com/docs/api/core/settlements/getv2summary get /v2/settlements/summaries Get a summarized list of settlement payouts. If your store accepts multiple currencies, you will need to request settlement summaries for each supported currency. If currency code is not provided in the request, the default currency will be USD. # Get details Source: https://docs.sezzle.com/docs/api/core/settlements/getv2summarydetail get /v2/settlements/details/{payout_uuid} Get details on a specific settlement payout. ```csv Response body theme={"system"} total_order_amount,total_capture_amount,total_refund_amount,total_fee_amount,total_returned_fee_amount,total_chargeback_amount,total_chargeback_reversal_amount,total_interest_transfer_amount,total_correction_amount,total_referral_revenue_transfer_amount,total_bank_account_withdrawals,total_bank_account_withdrawal_reversals,forex_fees,net_settlement_amount,payment_uuid,settlement_currency,payout_date,payout_status,final_payout_amount,payout_currency 703.20,703.20,-5.00,-43.80,.30,0.00,0.00,-4.30,1.71,10.00,100.00,-100.00,0.00,693.61,a5c13qt1-4126-41d3-2fq8-9ca431f51431,USD,2019-11-02 00:05:00 +0000 UTC,Complete,950.80,CAD type,order_capture_date,order_created_at,event_date,order_uuid,customer_order_id,external_reference_id,order_amount,amount,posting_currency,type_code,chargeback_code,sezzle_order_id,product_type,mid,card_network_auth_ref ORDER,2019-11-01T19:09:50Z,2019-11-01T19:09:50Z,2019-10-22T19:09:50Z,bm99f-31vu1-kg00e-rae1g,1,12345,500.00,,USD,001,,66d78e86-fd96-4266-9217-b769c102a0a0,standard_checkout,, ORDER,2019-11-01T19:09:50Z,2019-11-01T19:09:50Z,2019-10-22T19:09:50Z,va13d-474s9-3000e-nungg,13,12346,200.00,,USD,001,,5e0d4886-8c3d-4d4e-901a-2046a06c1e0f,long_term_lending,, ORDER,2019-11-01T20:00:01Z,2019-11-01T00:00:01Z,2019-11-01T00:00:01Z,as41g-4v4s9-3000e-nunh0,1,12347,1.40,,USD,001,,a2c1a142-96ad-48c9-93d2-1acaaee9f073,virtual_card,123456789,987654321 ORDER,2019-11-01T20:00:01Z,2019-11-01T20:00:01Z,2019-11-01T20:00:01Z,as62l-5ptqs-9g00e-pvk10,2,12348,1.80,,USD,001,,3f62dcba-f5a4-41be-ad8f-53e938b5f310,standard_checkout,, CAPTURE,2019-11-01T20:00:01Z,2019-11-01T20:00:01Z,2019-11-01T20:00:01Z,as62l-5ptqs-9g00e-pvk10,2,12348,,1.80,USD,001,,3f62dcba-f5a4-41be-ad8f-53e938b5f310,,, FEE,2019-11-01T19:09:50Z,2019-11-01T19:09:50Z,2019-11-01T19:09:50Z,bm99f-31vu1-kg00e-rae1g,1,12345,,-30.00,USD,003,,66d78e86-fd96-4266-9217-b769c102a0a0,,, FEE,2019-11-01T19:09:50Z,2019-11-01T19:09:50Z,2019-11-01T19:09:50Z,va13d-474s9-3000e-nungg,13,12346,,-12.00,USD,003,,5e0d4886-8c3d-4d4e-901a-2046a06c1e0f,,, FEE,2019-11-01T20:00:01Z,2019-11-01T00:00:01Z,2019-11-01T20:00:01Z,as41g-4v4s9-3000e-nunh0,1,12347,,-1.20,USD,003,,a2c1a142-96ad-48c9-93d2-1acaaee9f073,,, FEE,2019-11-01T20:00:01Z,2019-11-01T20:00:01Z,2019-11-01T20:00:01Z,as62l-5ptqs-9g00e-pvk10,2,12348,,-0.60,USD,003,,3f62dcba-f5a4-41be-ad8f-53e938b5f310,,, REFUND,2019-10-22T19:09:50Z,2019-10-22T19:09:50Z,2019-11-01T19:09:50Z,bm5rm-vg2js-1tsky-c2dsky,8,12344,,5.00,USD,002,,e4194956-de70-4958-9da4-6c05f276fdab,,, RETURNED_FEE,2019-10-22T19:09:50Z,2019-10-22T19:09:50Z,2019-11-01T19:09:50Z,bm5rm-vg2js-1tsky-c2dsky,7,12344,,.30,USD,004,,e4194956-de70-4958-9da4-6c05f276fdab,,, CORRECTION,,,2019-11-01T17:00:01Z,,,,,-1.29,,007,,,,, CORRECTION,,,2019-11-01T17:00:01Z,,,,,3.00,,007,,,,, INTEREST_TRANSFER,,,2019-11-01T18:00:01Z,,,,,-4.30,,008,,,,, REFERRAL_REVENUE_TRANSFER,,,2019-11-01T15:00:01Z,,,,,10.00,,009,,,,, BANK_ACCOUNT_WITHDRAWAL,,,2019-11-02T00:05:00Z,,,,,100.00,,010,,,,, BANK_ACCOUNT_WITHDRAWAL_REVERSAL,,,2019-11-02T00:05:00Z,,,,,-100.00,,011,,,,, ``` ## Payout Summary (rows 1-2) ### Summary Headers (row 1) | Column Header | Description | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Total order amount | The sum of all orders on this payout. | | Total captured amount | The sum of all captured amounts on this payout. | | Total refund amount | The sum of all refunds on this payout. | | Total fee amount | The sum of all fees on this payout. | | Total returned fee amount | The sum of all returned fees on this payout. | | Total chargeback amount | The sum of all chargebacks on this payout. | | Total chargeback reversal amount | The sum of all chargeback reversals on this payout. | | Total interest transfer amount | The sum of all interest transfers on this payout. If you are not participating in the interest program, this field will be omitted. | | Total correction amount | The sum of all corrections on this payout. | | Total referral revenue transfer amount | The sum of all referral revenue transfers on this payout. | | Total bank account withdrawal amount | The sum of all bank account withdrawals. | | Total bank account withdrawal reversal amount | The sum of all bank account withdrawal reversals, which reflect a bank account withdrawal that has failed. | | Forex fees | The cost of foreign exchange or cross border transfer fees associated with this payout. | | Net settlement amount | Net amount of settlement. | | Payment uuid | The UUID for this payout. | | Settlement currency | The ISO 4217 currency code of the amount to be settled | | Payout date | The date this payout was sent. | | Payout status | The current status of this payout. | | Final payout amount | The final amount sent to the recipient account after conversion. | | Payout currency | The ISO 4217 currency code in which the final payout amount was sent. | ## Line Items (rows 3-n) ### Line Item Headers (row 3) | Column Header | Description | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Type](#line-item-type) | Describes the type of event (Order, Fee, Refund, etc.). | | Order capture date | The date at which the order was captured. This field is empty if the order has not yet been captured. | | Order created at | The date at which the order was created. | | Event date | The date at which the event took place. | | Order uuid | The uuid associated with the order. | | Customer order id | The customer's order number. | | External reference id | The external reference ID submitted with the order. | | Order Amount | The order amount for the ORDER event | | Amount | The amount of the event. | | Posting currency | The customer's currency code. | | Type code | A numeric code that corresponds with the Type field. | | Chargeback code | A numeric code that corresponds with the type of chargeback submitted. | | Sezzle order ID | The internal ID Sezzle has assigned to this order. | | [Product type](#line-item-product-type) | Describes the type of merchant product (Affiliate, Gift card, Standard\_checkout, etc.) | | Merchant identification number (MID) | The ID that identifies the merchant and the legitimacy of the business and facilitates the movement of funds from the customer’s bank account to the merchant’s bank account. | | Card Network Auth Ref | A unique numeric or alphanumeric identifier assigned to credit card transactions, making it easier to locate and identify an individual credit card transaction. | #### Line Item Type | Type | Description | Type Code | | ----------------------------------- | ----------------------------------------------------------------------------- | --------- | | ORDER | A completed order with Sezzle. | 001 | | REFUND | An order that has been refunded. | 002 | | FEE | The fee assessed by Sezzle for a given order. | 003 | | RETURNED\_FEE | A fee refunded by Sezzle. | 004 | | CHARGEBACK | A chargeback resulting from a disputed order. | 005 | | CHARGEBACK\_REVERSAL | A reversal of a chargeback resulting from a disputed order. | 006 | | CORRECTION | A manual correction to a payout. | 007 | | INTEREST\_TRANSFER | A transfer from the Sezzle interest account. | 008 | | REFERRAL\_REVENUE\_TRANSFER | A payment earned from Sezzle's merchant referral program. | 009 | | BANK\_ACCOUNT\_WITHDRAWAL | A withdrawal of funds from your bank to cover a negative balance with Sezzle. | 010 | | BANK\_ACCOUNT\_WITHDRAWAL\_REVERSAL | A failed BANK\_ACCOUNT\_WITHDRAWAL. | 011 | | CAPTURE | An order that has been captured. | 012 | #### Line Item Product Type | Type | Description | | ------------------- | ------------------------------------------------- | | standard\_checkout | Standard pay in four checkout | | four\_pay\_monthly | 4 pay monthly order | | six\_pay\_monthly | 6 pay monthly order | | long\_term\_lending | Base long term lending product with no promotions | | virtual\_card | Virtual card order | # Delete webhooks Source: https://docs.sezzle.com/docs/api/core/webhooks/deletev2webhooks delete /v2/webhooks/{webhooks_uuid} Delete webhooks to unsubscribe This action cannot be undone, use with extreme caution # List webhooks Source: https://docs.sezzle.com/docs/api/core/webhooks/getv2webhooks get /v2/webhooks Get a list of webhooks you are subscribed to ### Valid Webhook Events We accept the following Webhook events | Event | Trigger | | :--------------------------------- | :------------------------------------------------------------------ | | `customer.tokenized` | A customer is tokenized | | `order.authorized` | An order is authorized by Sezzle | | `order.captured` | An order is captured by Sezzle | | `order.refunded` | An order is refunded by Sezzle | | `dispute.merchant_input_requested` | A dispute is filed by a shopper and merchant input is required | | `dispute.deadline_approaching` | A dispute is moved to final notice by Sezzle | | `dispute.closed.customer_win` | The shopper wins the dispute and the order is refunded | | `dispute.closed.merchant_win` | The merchant wins the dispute and it is resolved in their favor | | `dispute.closed.neutral` | No clear winner is determined and the dispute is resolved neutrally | # Webhook Signature, Acceptance and Retries Source: https://docs.sezzle.com/docs/api/core/webhooks/infov2webhooks ## Webhook Signature * Secured with HMAC-SHA256 signature. * Sezzle-Signature header contains a hash of the webhook body, generated using the merchant private key. * Always verify the signature matches the webhook data to confirm it originates from Sezzle. ## Webhook Event Payload Unique identifier for the webhook event. Timestamp (ISO 8601) when the event was generated. Type of the event Available options: `customer.tokenized`, `order.authorized`, `order.captured`, `order.refunded`, `dispute.merchant_input_requested`, `dispute.deadline_approaching`, `dispute.closed.customer_win`, `dispute.closed.merchant_win`, `dispute.closed.neutral` Type of data associated with the event. Available options: `customer`, `order`, `dispute` Payload data specific to the event type. See options in the applicable accordion below. ```json theme={"system"} { "uuid": string, "created_at": string, "event": string, "data_type": string, "data": { "token": string, "expiration": string, "customer": { "uuid": string, "created_at": string, "expiration": string } } } ``` ### Examples per Event ```json theme={"system"} { "uuid": "e41c32d5-687d-414f-b5c6-d089bea52e7d", "created_at": "2025-04-12T00:11:01.749261Z", "event": "customer.tokenized", "data_type": "tokenize", "data": { "token": "ce56604a-5dfd-489a-80e9-753d0325dd46", "expiration": "2025-04-12T00:41:01.745145Z", "customer": { "uuid": "e0003e6a-7234-4440-9265-61906e8b8879", "created_at": "2025-04-12T00:11:01.745145Z", "expiration": "2026-04-12T00:11:01.745145Z" } } } ``` * The `"uuid"` is the webhook UUID * The `"data.uuid"` is the order UUID that can be used on the API call to get order details * The `"data.authorization.uuid"` is the UUID for the authorization ```json theme={"system"} { "uuid": "fdb263a1-a1dd-4feb-8749-c8a447977ebb", "created_at": "2025-04-12T00:15:39.281826Z", "event": "order.authorized", "data_type": "order", "data": { "uuid": "f36605a0-4a96-46d1-9d01-a0b17140dc57", "authorization": { "uuid": "28ef487d-8398-43bb-8354-5ebdd1eb7b40", "created_at": "2025-04-12T00:15:39.276841Z", "authorization_amount": { "amount_in_cents": 5000, "currency": "USD" }, "approved": true, "expiration": "2025-04-12T00:45:39.276841Z" } } } ``` * The `"uuid"` is the webhook UUID * The `"data.uuid"` is the order UUID that can be used on the API call to get order details * The `"data.capture.uuid"` is the UUID for the capture ```json theme={"system"} { "uuid": "6ee025c6-8acf-48fe-a6d6-b51693d64c60", "created_at": "2025-04-12T00:20:07.44668Z", "event": "order.captured", "data_type": "order", "data": { "uuid": "b87305a1-6be3-4877-bcf0-2b5b7dfaeaf0", "capture": { "uuid": "b69b1ba8-e977-4f26-9253-06f14d941696", "created_at": "2025-04-12T00:20:07.438365Z", "amount": { "amount_in_cents": 3000, "currency": "USD" } } } } ``` * The `"data.uuid"` is the order UUID that can be used on the API call to get order details Note on the `source` field: * If the value is `"dashboard"`, it's initiated from the merchant dashboard * If the value is `"gateway"`, it's via the gateway API ```json theme={"system"} { "uuid": "ed89f046-f55e-4fdd-9f65-ec3d8e961f99", "created_at": "2025-04-12T00:24:39.809499Z", "event": "order.refunded", "data_type": "order", "data": { "uuid": "b69f882d-06c3-4f2e-b6e3-ce7a6c46e455", "refund": { "uuid": "479e9d25-d0a5-49df-a2d3-6ca1d75b8c57", "created_at": "2025-04-12T00:24:39.805651Z", "source": "dashboard", "amount": { "amount_in_cents": 500, "currency": "USD" } } } } ``` The following applies to the following webhooks: * `dispute.merchant_input_requested` * `dispute.deadline_approaching` * `dispute.closed.customer_win` * `dispute.closed.merchant_win` * `dispute.closed.neutral` ```json theme={"system"} { "uuid": "79f1e9cd-f1ef-42fa-b7b4-2ed8d9e9fae8", "created_at": "2025-04-11T17:22:22.717757Z", "event": "dispute.merchant_input_requested", "data_type": "dispute", "data": { "customer_name": "John Doe", "order_uuid": "e17280f3-d575-4bc2-99ff-ff881df7b137", "order_reference_id": "order-reference-id-123", "sezzle_order_id": "d2s7t-281qj-rf6ra-dqfcg", "order_date": "2024-08-20", "dispute_type": "No Product Or Service", "dispute_due_date": "2025-04-08", "dispute_id": 132, "dispute_amount_in_cents": 2500, "dispute_currency": "USD", "dispute_status": "Closed All Win" } } ``` ## Webhook Acceptance and Retries * Considered delivered upon receiving an HTTP 200 Status OK response. * Non-200 responses trigger retries: * Multiple attempts in the first hour. * A few attempts throughout the day. * Final attempts one day and three days later, spanning five days total. * If the final retry fails, the webhook subscription is deleted for all events. * To resume receiving webhooks, recreate the webhook. * Webhooks may not arrive in chronological order, as new ones can be sent before retries of older ones. * Retried webhooks use the current merchant private key for signing, so the signature may differ from the original if the key has changed. # Update webhook Source: https://docs.sezzle.com/docs/api/core/webhooks/patchv2webhooks patch /v2/webhooks/{webhooks_uuid} Update an existing webhook configuration (URL and/or events) Use this endpoint to update an existing webhook configuration. You can modify both the webhook URL and the events subscribed to. ### Valid Webhook Events We accept the following Webhook events | Event | Trigger | | :--------------------------------- | :------------------------------------------------------------------ | | `customer.tokenized` | A customer is tokenized | | `order.authorized` | An order is authorized by Sezzle | | `order.captured` | An order is captured by Sezzle | | `order.refunded` | An order is refunded by Sezzle | | `dispute.merchant_input_requested` | A dispute is filed by a shopper and merchant input is required | | `dispute.deadline_approaching` | A dispute is moved to final notice by Sezzle | | `dispute.closed.customer_win` | The shopper wins the dispute and the order is refunded | | `dispute.closed.merchant_win` | The merchant wins the dispute and it is resolved in their favor | | `dispute.closed.neutral` | No clear winner is determined and the dispute is resolved neutrally | ### Notes * Both `url` and `events` fields are required in the request body * The webhook URL must be unique per merchant - you cannot update to a URL that is already in use by another webhook * If the webhook UUID is not found, a 404 error will be returned * Event subscriptions are replaced entirely - specify all events you want to receive, not just the changes # Create webhooks Source: https://docs.sezzle.com/docs/api/core/webhooks/postv2webhooks post /v2/webhooks This endpoint can be used to subscribe to webhooks ### Valid Webhook Events We accept the following Webhook events | Event | Trigger | | :--------------------------------- | :------------------------------------------------------------------ | | `customer.tokenized` | A customer is tokenized | | `order.authorized` | An order is authorized by Sezzle | | `order.captured` | An order is captured by Sezzle | | `order.refunded` | An order is refunded by Sezzle | | `dispute.merchant_input_requested` | A dispute is filed by a shopper and merchant input is required | | `dispute.deadline_approaching` | A dispute is moved to final notice by Sezzle | | `dispute.closed.customer_win` | The shopper wins the dispute and the order is refunded | | `dispute.closed.merchant_win` | The merchant wins the dispute and it is resolved in their favor | | `dispute.closed.neutral` | No clear winner is determined and the dispute is resolved neutrally | # Trigger a test webhook Source: https://docs.sezzle.com/docs/api/core/webhooks/postv2webhooktest post /v2/webhooks/test Trigger a test event to mimic a webhook event at a given URL. ### Valid Webhook Events We accept the following Webhook events | Event | Trigger | | :--------------------------------- | :------------------------------------------------------------------ | | `customer.tokenized` | A customer is tokenized | | `order.authorized` | An order is authorized by Sezzle | | `order.captured` | An order is captured by Sezzle | | `order.refunded` | An order is refunded by Sezzle | | `dispute.merchant_input_requested` | A dispute is filed by a shopper and merchant input is required | | `dispute.deadline_approaching` | A dispute is moved to final notice by Sezzle | | `dispute.closed.customer_win` | The shopper wins the dispute and the order is refunded | | `dispute.closed.merchant_win` | The merchant wins the dispute and it is resolved in their favor | | `dispute.closed.neutral` | No clear winner is determined and the dispute is resolved neutrally | # Environments Source: https://docs.sezzle.com/docs/api/environments Before going live, you may test your integration with Sezzle using the Sezzle sandbox test environment, rather than the live production environment. Only one environment's dashboard session can be active at a time. If a user is logged in to production then logs in to sandbox on another tab, the production session will end, and vice versa. ## **Accessing Sandbox Environments** * A merchant who registers for a Sezzle production account automatically receives a matching sandbox account upon approval * Default admin users for the production dashboard are imported to the sandbox dashboard upon creation. As with production, sandbox Admin users on can invite additional staff [here](https://sandbox.dashboard.sezzle.com/merchant/invite-user). * Merchants can create a standalone sandbox account without a production account, ideal for testing production features without becoming a Sezzle merchant (e.g., during system integration) 1. [Sign up for Sandbox](https://sandbox.dashboard.sezzle.com/merchant/signup) * Phone number and email address must be valid, all other information can be fake 2. Complete email verification and security setup 3. Complete `Personal Information` and `Business Information` sections of the Setup Checklist, then click `Submit for Approval` * This information can also be fake * In Production environment, `Credit or Debit Card` and `Bank Account` steps must also be completed before API keys can be generated. 4. Contact your account manager or [Sezzle Support](https://dashboard.sezzle.com/merchant/contact) for account approval When starting with a standalone account, you must complete a Production merchant signup separately and manually. The two accounts will not be linked in these cases. ## Testing Your Integration 1. Log in to your [sandbox](https://sandbox.dashboard.sezzle.com/merchant) account * Production account users: Log in using the same credentials as production Merchant Dashboard * OTP will always be `123123` for Sandbox. Emails and text messages will not be sent. 2. In the left toolbar, go to `Settings` > `API Keys` 3. Click the button labeled `create API key` * API keys for sandbox and production are not interchangeable: * Sandbox API keys cannot be used in the production dashboard. * Production API keys cannot be used in the sandbox. * The sandbox gateway URL is [https://sandbox.gateway.sezzle.com](https://sandbox.gateway.sezzle.com). 4. Complete the `Add Sezzle as a payment option at your checkout` step of the setup checklist, enabling Test Mode * Bank account and currency settings can be skipped 5. Start a checkout on your store website 6. Select `Sezzle` as the payment method 7. Complete the Sezzle checkout using the [test data](/docs/api/test-cards) 8. Verify that the order is successful Refer to [Postman Setup section](./postman-setup.mdx) on how to programmatically create orders and more leveraging [Sezzle Core API](/docs/api/core). If you wish to test **on-site messaging widgets** in Sandbox environment, you must use Production URL and merchant UUID. If you do not have a Production account, please contact Sezzle Support for options. # Errors Source: https://docs.sezzle.com/docs/api/errors Endpoints will return an array of standardized error objects on failures. We attempt to keep these errors as consistent as possible, and will announce any changes in advance if they are required. ## Error Response ```json theme={"system"} [ { "code": string, "location": string, "message": string, "debug_uuid": string } ] ``` ```json theme={"system"} [ { "code": "invalid", "location": "order.amount.amount_in_cents", "message": "Order amount must be greater than $35", "debug_uuid": "919f40d0-874b-4d98-810d-ed2246a8ad77" } ] ``` Error code Where the error occurred Message describing why error occured UUID identifying error # Introduction Source: https://docs.sezzle.com/docs/api/intro * Sezzle supports individually-authorized transactions for single purchases, with the latest version enabling customer tokenization for future transactions. * Integration options include: * Direct API integration * Lightweight JavaScript SDK * Integrations with popular eCommerce platforms * [Contact the Sezzle team](https://merchant-help.sezzle.com/hc/en-us/requests/new) for API-related questions. * An approved Sezzle account is required to start integration; [sign up](https://dashboard.sezzle.com/merchant/signup) if you don’t have one. Assume that all API methods require an [Authorization bearer token](./core/authentication/postauthentication#authenticated-call-http-header). ## Direct Integration Quick Start 1. Use API keys to obtain an [authentication token](./core/authentication/postauthentication) 2. [Create a session](./core/sessions/postv2session) with an [order object](./core/sessions/postv2session#body-order) 3. Redirect user to Sezzle checkout URL 4. User completes Sezzle checkout 5. Sezzle redirects user back to [merchant complete URL](./core/sessions/postv2session#body-complete-url) 6. Manage the order with the [Order API](./core/orders/getv2order) ## Open API Specification * The [OpenAPI Specification (OAS)](https://swagger.io/specification/) offers a standard, language-independent interface for RESTful APIs, allowing humans and machines to understand service capabilities without source code, documentation, or network traffic analysis. * Access the [Sezzle v2 OpenAPI Specification](https://gateway.sezzle.com/v2api.yaml) for integration details. * Import the Sezzle v2 OpenAPI Specification into the [Swagger Editor](https://editor.swagger.io/?url=https://gateway.sezzle.com/v2api.yaml) to generate a Sezzle client in multiple programming languages. * For languages unsupported by Swagger, use [OpenAPI Generator](https://openapi-generator.tech/) as an alternative tool. # Postman Setup Source: https://docs.sezzle.com/docs/api/postman-setup The Sezzle team has prepared a public Postman collection so merchants can quickly create customers (Sezzle users), sessions, and orders for sandbox testing. ### Download and Install Postman 1. Go to [postman.com/downloads](https://www.postman.com/downloads) 2. Click `Download the App` 3. When the installation file has finished downloading, click the file to install the application 4. Follow installation prompts on the screen ### Add Sezzle Gateway Collection When installation is complete, follow these steps to add the Sezzle Gateway collection to Postman. 1. [Download the Postman collection](https://god.gw.postman.com/run-collection/9737967-e6ff8257-718a-4206-b6f0-7540e3b97060?action=collection%2Ffork\&collection-url=entityId%3D9737967-e6ff8257-718a-4206-b6f0-7540e3b97060%26entityType%3Dcollection%26workspaceId%3Dcf7fd793-2599-4aed-9b55-0871e7b27e1a) 2. In the Web page that opens, select your operating system 3. Click `Open Postman` if prompted 4. In Postman, the Sezzle Gateway collection is now displayed in the Collections tab ### Edit environment variables The collection is prepared with `SezzleGatewayURL`, `SezzlePrivateAPIKey`, and `SezzlePublicAPIKey` saved to the collection variables. However, it is recommended to save these as Environment variables instead so you can easily toggle between Sandbox and Production, and to keep API keys secret. 1. In the left toolbar, click Environments 2. If you have never used Environment variables before, click the `+` icon and name the new environment `Sandbox` 3. Create the new variables as follows: | Variable | Type | Initial value | | ------------------- | ------- | ------------------------------------------------------------------------ | | SezzleGatewayURL | default | [https://sandbox.gateway.sezzle.com](https://sandbox.gateway.sezzle.com) | | SezzlePrivateAPIKey | secret | sz\_pr... | | SezzlePublicAPIKey | secret | sz\_pub... | 4. Next, copy your API Keys from the Sezzle Sandbox Dashboard into Postman. 1. To access your credentials, log in to the [Sezzle Sandbox Dashboard](https://sandbox.dashboard.sezzle.com/merchant/) 2. Go to `Settings` > `API Keys` - your sandbox credentials are [here](https://sandbox.dashboard.sezzle.com/merchant/settings/apikeys) 3. In Postman, paste your credentials into `CURRENT VALUE` * Do this for both `SezzlePublicAPIKey` and `SezzlePrivateAPIKey` 5. Repeat for Environment `Production`, with `SezzleGatewayURL` as `https://gateway.sezzle.com` and API keys from [Sezzle Production Dashboard](https://dashboard.sezzle.com/merchant/) API Keys do not translate across environments, i.e. Production API Keys will not work in Sandbox testing. Only one environment’s dashboard session can be active in the browser at a time. If a user is logged in to production then logs in to sandbox on another tab, the production session will end, and vice versa. 6. In the left toolbar, click Collections 7. Click Sezzle Gateway. On the Variables tab, delete the variables we just created in Environments The other predefined collection variables will be automatically assigned values by the applicable responses and applied to subsequent requests. ### Using the collection 1. In the upper-right corner of Postman, select the desired environment (i.e. Sandbox) 2. Open the applicable folder for your API version (default V2) 3. Refer to the below diagrams for request sequencing V2 Gateway Request Flow

3. Once a session is created, you must visit the checkout\_url in the response and complete the checkout before testing most other Orders endpoints. * Log in at sandbox.dashboard.sezzle.com/customer * The customer account does not need to match the customer details given in the session payload * The phone number for the customer account must be real, but other personal information can be fake * OTP will be `123123` # Test Data Source: https://docs.sezzle.com/docs/api/test-cards Test data is important to use in our Sandbox environment because it offers a way to use reliable forced responses. ## Phone and Personal Information * Use any valid US or CA phone number, real or fake * The expected OTP is `123123` * Personal information does not need to be real ## Test Credit Cards | Brand | Number | CVC | Expiration | | ---------- | ---------------- | ------------ | --------------- | | Visa | 4242424242424242 | Any 3 digits | Any future date | | Mastercard | 5555555555554444 | Any 3 digits | Any future date | | Amex | 371449635398431 | Any 4 digits | Any future date | | Amex | 378282246310005 | Any 4 digits | Any future date | | Discover | 6011111111111117 | Any 3 digits | Any future date | ## Checkout Testing * Use your [sandbox API keys](https://sandbox.dashboard.sezzle.com/merchant/settings/apikeys) when testing in a test environment * Use your [production API keys](https://dashboard.sezzle.com/merchant/settings/apikeys) when testing in a live environment 1. On your website, add an item to your cart, then proceed to Checkout and select `Sezzle` as the payment method 2. Click `Place Order` If you are redirected to the Sezzle checkout page, your integration is complete. 3. In sandbox, use the above test data to complete the Sezzle checkout and you should be redirected back to your website In production, **BE CAREFUL** when completing the Sezzle checkout, as you will be charged. You can identify the Sezzle environment by observing if "sandbox" is included in the Sezzle checkout URL. # Delete a customer Source: https://docs.sezzle.com/docs/api/tokenization/customers/deletev2token delete /v2/customer/{customer_uuid} Delete an existing tokenized customer # Get a customer Source: https://docs.sezzle.com/docs/api/tokenization/customers/getv2customer get /v2/customer/{customer_uuid} Get details on an existing tokenized customer # Get a list of customers Source: https://docs.sezzle.com/docs/api/tokenization/customers/getv2customerlist get /v2/customer Retrieve a list of existing tokenized customers # Create order by customer Source: https://docs.sezzle.com/docs/api/tokenization/customers/postv2customerorder post /v2/customer/{customer_uuid}/order Create an order for a tokenized customer It is extremely important to note this API will return a 200 success if the request to create an order is successful (i.e. no errors) but the customer could not be approved for the order. **Note:** If you plan to tokenize a customer for the purpose of creating orders by a customer, please be advised that these orders will not include any financing options. # Preapprove amount by customer Source: https://docs.sezzle.com/docs/api/tokenization/customers/preapprovev2token post /v2/customer/{customer_uuid}/preapprove Verify tokenized customer will be approved for the amount of the order prior to order creation. This API does not authorize the amount nor does it hold the amount for a future order. Also, you are not required to use this API before creating a customer order. An example use-case is to verify approval status ahead of subscription payment due date, and to contact the customer in advance to avoid failed payment. # Introduction Source: https://docs.sezzle.com/docs/api/tokenization/intro Customer tokenization allows merchants to store Sezzle as a payment method for future orders without customer interaction, ideal for subscriptions like semi-annual charges. All tokenized orders will be processed as Pay in Full. The approval URL was deprecated in April 2025. Now, the only way for customers to authorize you to process future transactions on tokenized orders is by selecting that option in the initial checkout process. To obtain that authorization: 1. Initiate and tokenize the order in a single session 2. Redirect the customer to the checkout URL For detailed instructions, view the Tokenization Process below. ## Tokenization Process Group7 Pn

1. Tokenize Customer via Checkout * The merchant calls `/v2/session` with `tokenize: true`, optionally including customer details to speed up registration for new Sezzle users. * Sezzle returns a session `tokenize` token. 2. Merchant Redirects User to Checkout URL * Customer sees option to allow merchant to process payments from their Sezzle account for future transactions. * The customer may decide to allow this permission before completing their checkout. The only way for customers to authorize you to process future transactions on tokenized orders is by selecting that option in the initial checkout process. Image Pn

* If agreed, Sezzle redirects back to the merchant’s session complete URL, appending a `customer-uuid` query parameter. * Alternatively, the merchant can call `/v2/token` with the session tokenize token to retrieve the UUID. 3. Charge Customer * The merchant uses the `customer-uuid` to create orders via `/v2/customer/{customer_uuid}/order`. * If the authorization is approved, the merchant can manage the order (release, capture, or refund) using `/v2/order` endpoints. ## Notes * Tokenization is optional, recommended only for charging via Sezzle outside standard checkouts. * Orders created via customer UUID are treated the same as those from a standard Sezzle checkout. ## Customers Use the customers endpoints to: * [Delete](/docs/api/tokenization/customers/deletev2token) a customer * [Get](/docs/api/tokenization/customers/getv2customer) details on an existing customer * [Get](/docs/api/tokenization/customers/getv2customerlist) a list of customers * [Create](/docs/api/tokenization/customers/postv2customerorder) an order for a customer * [Preapprove](/docs/api/tokenization/customers/preapprovev2token) an amount for the customer Customers are only those Sezzle users that have agreed to be tokenized by the merchant. A customer is unique to a merchant. This API does not include all Sezzle users. # Get session tokenization Source: https://docs.sezzle.com/docs/api/tokenization/session/getv2sessiontoken get /v2/token/{token}/session Get the current state of a tokenization session. # Complete a Checkout Source: https://docs.sezzle.com/docs/api/v1/complete-a-checkout post /v1/checkouts/{order_reference_id}/complete Initiate order payment capture if `merchant_completes` was `true` at Create Checkout. An example use-case is if users need to return to the merchant's site before finalizing the purchase with Sezzle. Submit the Complete Checkout request within 30 minutes after the user is redirected to the merchant's site. Failure to do so results in Sezzle canceling the checkout. The default expiration period for new orders can be extended up to 7 days via the Merchant Dashboard. You are viewing Version 1 of the Sezzle API. Check out the [current version](/docs/api/intro)! # Create a Checkout Source: https://docs.sezzle.com/docs/api/v1/create-a-checkout post /v1/checkouts Initiate a Sezzle session with shopper order details, redirect links, and capture settings You are viewing Version 1 of the Sezzle API. Check out the [current version](/docs/api/intro)! # Interest Account Activity Request Source: https://docs.sezzle.com/docs/api/v1/interest-account-reports/interest-account-activity-request get /v1/interest/activity If you are enrolled in the interest account program, get the current activity on the interest account. You are viewing Version 1 of the Sezzle API. Check out the [current version](/docs/api/intro)! # Interest Account Balance Request Source: https://docs.sezzle.com/docs/api/v1/interest-account-reports/interest-account-balance-request get /v1/interest/balance If you are enrolled in the interest account program, get the current balance on the interest account. Fractions of cents are tracked to properly calculate daily interest accrual even if the interest balance is low. You are viewing Version 1 of the Sezzle API. Check out the [current version](/docs/api/intro)! # Obtain Authentication Token Source: https://docs.sezzle.com/docs/api/v1/obtain-authentication-token post /v1/authentication Generate authentication token from your Sezzle merchant API keys for use in the header of all other API requests. You are viewing Version 1 of the Sezzle API. Check out the [current version](/docs/api/intro)! # Orders Source: https://docs.sezzle.com/docs/api/v1/orders get /v1/orders/{order_reference_id} Get details and check the status of an existing order You are viewing Version 1 of the Sezzle API. Check out the [current version](/docs/api/intro)! # Refund Request Source: https://docs.sezzle.com/docs/api/v1/refund-request post /v1/orders/{order_reference_id}/refund Refund an amount by order, either partial or in full. An example use-case is when an order was captured but the customer returned item(s) that requires them to be refunded. You are viewing Version 1 of the Sezzle API. Check out the [current version](/docs/api/intro)! # Setting Your Configuration Source: https://docs.sezzle.com/docs/api/v1/setting-your-configuration post /v1/configuration Configure webhook URL You are viewing Version 1 of the Sezzle API. Check out the [current version](/docs/api/intro)! ## Webhooks ### Order Webhooks * Sezzle handles most of the consumer checkout process on its pages, using webhooks to notify your system about: * Checkout updates * Completions * Refunds * Use the instructions in this page to subscribe to Webhooks * When a webhook event occurs, Sezzle will send the below Webhook object to the URL provided in the configuration ### Order Webhook Object ```json theme={"system"} { "time": string, "uuid": string, "type": string, "event": string, "object_uuid": string, "refund_id": string, "refund_amount": { "amount_in_cents": number, "currency": string } } ``` ```json theme={"system"} { "time": "2017-10-19T00:33:10.548372055Z", "uuid": "02c5a2a0-8394-4b45-80b3-52d40c494322", "type": "order_update", "event": "order_complete", "object_uuid": "Ref123456789", "refund_id": "szl-a0293Pn-3948-80b3-ao34JAia39zQ", "refund_amount": { "amount_in_cents": 500, "currency": "USD" } } ``` The time (UTC) at which the Webhook was generated. A unique identifier for the webhook. The high-level category. Available options: `order_update` (coming soon) The ID for the Checkout/Order. Available options: `order_complete`, `order_refund` The ID for the Checkout/Order. For order update webhooks, the `object_uuid` returned is the reference ID provided during checkout creation by the merchant Unique ID for a refund. Included if the webhook event is order\_refund Price object. Included if the webhook event is order\_refund. The amount in cents The 3 character currency code as defined by ISO 4217 # Settlement Details Request Source: https://docs.sezzle.com/docs/api/v1/settlement-reports/settlement-details-request get /v1/settlements/details/{payout_uuid} Get details on a specific settlement payout. You are viewing Version 1 of the Sezzle API. Check out the [current version](/docs/api/intro)! The settlement details response contains two sections. The first two rows are a summary of the payout. The remaining rows contain the individual line items that contributed to the payout. ### Summary Column Definitions | Column Header | Description | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `Total order amount` | The sum of all orders on this payout. | | `Total refund amount` | The sum of all refunds on this payout. | | `Total fee amount` | The sum of all fees on this payout. | | `Total returned fee amount` | The sum of all returned fees on this payout. | | `Total chargeback amount` | The sum of all chargebacks on this payout. | | `Total chargeback reversal amount` | The sum of all chargeback reversals on this payout. | | `Total interest transfer amount` | The sum of all interest transfers on this payout. If you are not participating in the interest program, this field will be omitted. | | `Total correction amount` | The sum of all corrections on this payout. | | `Total referral revenue transfer amount` | The sum of all referral revenue transfers on this payout. | | `Total bank account withdrawal amount` | The sum of all bank account withdrawals. | | `Total bank account withdrawal reversal amount` | The sum of all bank account withdrawal reversals, which reflect a bank account withdrawal that has failed. | | `Forex fees` | The cost of foreign exchange fees associated with this payout. | | `Net settlement amount` | Net amount of settlement. | | `Payment uuid` | The UUID for this payout. | | `Settlement currency` | The currency in which this payout was sent. | | `Payout date` | The date this payout was sent. | | `Payout status` | The current status of this payout. | ### Line Item Column Definitions | Column Header | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------- | | `Type` | Describes the type of event (Order, Fee, Refund, etc.). | | `Order capture date` | The date at which the order was captured. This field is empty if the order has not yet been captured. | | `Order created at` | The date at which the order was created. | | `Event date` | The date at which the event took place. | | `Order uuid` | The uuid associated with the order. | | `Customer order id` | The customer's order number. | | `External reference id` | The external reference ID submitted with the order. | | `Amount` | The amount of the event. | | `Posting currency` | The customer's currency code. | | `Type code` | A numeric code that corresponds with the Type field. | | `Chargeback code` | A numeric code that corresponds with the type of chargeback submitted. | | `Sezzle order ID` | The internal ID Sezzle has assigned to this order. | | | | ### Line Item Event Type Definitions | Type | Description | Type Code | | ---------------------------------- | ----------------------------------------------------------------------------- | --------- | | `ORDER` | A completed order with Sezzle. | 001 | | `REFUND` | An order that has been refunded. | 002 | | `FEE` | The fee assessed by Sezzle for a given order. | 003 | | `RETURNED_FEE` | A fee refunded by Sezzle. | 004 | | `CHARGEBACK` | A chargeback resulting from a disputed order. | 005 | | `CHARGEBACK_REVERSAL` | A reversal of a chargeback resulting from a disputed order. | 006 | | `CORRECTION` | A manual correction to a payout. | 007 | | `INTEREST_TRANSFER` | A transfer from the Sezzle interest account. | 008 | | `REFERRAL_REVENUE_TRANSFER` | A payment earned from Sezzle's merchant referral program. | 009 | | `BANK_ACCOUNT_WITHDRAWAL` | A withdrawal of funds from your bank to cover a negative balance with Sezzle. | 010 | | `BANK_ACCOUNT_WITHDRAWAL_REVERSAL` | A failed BANK\_ACCOUNT\_WITHDRAWAL. | 011 | | `CAPTURE` | An order that has been captured. | 012 | | `MONTHLY_FEE` | Monthly Minimum Processing Fee (negative amount). | 013 | | `MONTHLY_FEE_REFUND` | Refund of a previously charged Monthly Minimum Processing Fee. | 014 | # Settlement Summaries Request Source: https://docs.sezzle.com/docs/api/v1/settlement-reports/settlement-summaries-request get /v1/settlements/summaries Get a summarized list of settlement payouts. You are viewing Version 1 of the Sezzle API. Check out the [current version](/docs/api/intro)! # v1 Overview Source: https://docs.sezzle.com/docs/api/v1/v1 You are viewing Version 1 of the Sezzle API. Check out the [current version](/docs/api/intro)! * Sezzle API v1 is designed for merchants wanting to accept Sezzle as a payment option. * The Sezzle [Integration Flow](#integration-flow) outlines the user payment interaction process. * Sezzle supports individually authorized transactions for single purchases of goods or services. * An approved Sezzle account is required to begin integration; visit the [signup page](https://dashboard.sezzle.com/merchant/signup) to create one if needed. ## Testing While you are working on the integration, you should test it in a sandbox environment before going live. ### Sandbox **API Endpoint** `https://sandbox.gateway.sezzle.com/v1`\ **Sandbox Dashboard** `https://sandbox.dashboard.sezzle.com/merchant` Credentials to log in to the sandbox dashboard are the same ones you use to log in to the Sezzle Merchant Dashboard. You can create your test API keys in the [sandbox dashboard](https://sandbox.dashboard.sezzle.com/merchant/settings/apikeys). ### Test Data You can use the following test data to test your integration: | Bank | Username | Password | | ----------- | -------- | -------- | | `Test Bank` | `demo` | `go` | | Card Number | CVV/CVC | Expiration Data | Name | Address | | ------------------ | ----------------- | --------------- | ----- | ------- | | `4242424242424242` | `any (3 numbers)` | `any` | `any` | `any` | ### Phone and other information * Please use any valid phone number * The expected `OTP` is `123123` * Personal information does not need to be real ## Open API Specification * The [OpenAPI Specification (OAS)](https://swagger.io/specification/) offers a standard, language-independent interface for RESTful APIs, allowing humans and machines to understand service capabilities without source code, documentation, or network traffic analysis. * Access the [Sezzle v2 OpenAPI Specification](https://gateway.sezzle.com/v2api.yaml) for integration details. * Import the Sezzle v2 OpenAPI Specification into the [Swagger Editor](https://editor.swagger.io/?url=https://gateway.sezzle.com/v2api.yaml) to generate a Sezzle client in multiple programming languages. * For languages unsupported by Swagger, use [OpenAPI Generator](https://openapi-generator.tech/) as an alternative tool. ## Integration Flow Api Flow Pn

### Payment Flow Explanation 1. Merchant calls `/v1/checkouts` to send cart data to Sezzle 2. Sezzle returns URL to redirect consumer to make payment at Sezzle checkout 3. Merchant redirects the consumer to Sezzle 4. When the consumer completes the Sezzle checkout flow, they are redirected back to merchant's website 5. Alternatively, on approval, the consumer is redirected from Sezzle checkout to merchant's website and merchant captures the order by calling `/v1/complete` ### Refund Request | Parameter | Type | Description | | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `amount*` | object | A price object that defines the amount to be refunded. Amount may not be 0, negative, or exceed the total order amount. Currency must either be the order's currency or the customer's paying currency. This field is optional if the `is_full_refund` parameter is true. | | `refund_id` | string | UUID for the Refund. Must be unique to a Merchant. | | `refund_reason` | string | A reason for the refund. | | `is_full_refund` | boolean | Overrides `amount`. If true, the order will be fully refunded. If omitted, will default to false | ## Javascript SDK The Javascript SDK is documented in the latest [API v2 documentation](/#javascript-sdk). It is supported for users of the v1 API using the same loadable page script. When using the Javascript SDK with v1, use apiVersion: "v1" in the Checkout constructor. ### Create a Checkout ```javascript theme={"system"} checkout.startCheckout({ checkout_payload: { "amount_in_cents": 12999, "currency_code": "USD", "order_reference_id": "Ref123456789", "order_description": "Order #1800", } }); ``` * Using the Javascript SDK with v1: * Create a checkout with the Checkout Object. * Complete the checkout using the Complete a Checkout endpoint. * The v1 endpoint: * Captures the total order amount. * Does not require a request body. * Do not use the payload object shown in the example capture for v1. ### Complete a Checkout ```javascript theme={"system"} checkout.capturePayment("Ref123456789"); ``` ## On-Site Messaging Widget SDK * The On-Site Messaging Widget SDK loads Sezzle promotional widgets onto web pages. * Widgets require a config to be provided before the script loads, or they will not display. * The project repository is available at [https://github.com/sezzle/sezzle-js](https://github.com/sezzle/sezzle-js). * Refer to the latest documentation for widget configuration details. # About Sezzle Page Source: https://docs.sezzle.com/docs/guides/about-sezzle Including a dedicated page about Sezzle on your website helps customers understand how Sezzle works and highlights the benefits of using it as a payment option. We provide a pre-made HTML template to simplify the process. To get started: 1. Select your website platform 2. Copy the code from the "Code Snippets" section and integrate it into your site to create the page To see a sample of what the page looks like, click [here](https://sezzle-test.myshopify.com/pages/how-sezzle-works). ## Shopify Process To set up the page on Shopify, follow the steps below. 1. Log in to your Shopify Store 2. Navigate to `Online Store` > `Themes` 3. On the theme you want to edit, select `Actions` and then `Edit Code` 4. Under the `Templates` folder, click `Add New Template`, select template for `Page`, template type `liquid`, and name the page `Sezzle`, then click `Create Template` 5. Select the theme that best fits your store from the tabs listed 6. Copy the code and paste it under `{{page.content}}` on the Shopify page 7. Save 8. Navigate to `Pages` 9. Add a new page, and give it a title - we recommend something like `How Sezzle Works` or `How to use Sezzle` 10. Under `Theme Template` (in the bottom-right), select `sezzle` 11. Save and view the page ## Add the page to your navigation 1. Go to `Online Store` > `Navigation` 2. Select the menu where you would like the Sezzle link to appear (ex: Main menu) 3. Click `Add menu item` 4. Enter the text you wish to appear (ex: How Sezzle Works) 5. Click the second box, select `Pages` then the page you just created 6. Click `Add` 7. Click `Save Menu` ## Lightspeed Process Due to Lightspeed restrictions which prevent `script` and `style` tags being saved in Pages, our standard installation script is incompatible. Below are the instructions to install the HTML and CSS separately from an older version of our code. 1. Log into your store admin 2. Navigate to `Content` > `Add Page` 3. Enter Title: `About Sezzle` or `How Sezzle Works` 4. Under Content, click the `<>` button 5. Copy+paste the code from [Github](https://github.com/sezzle/sezzle-merchant-resources/blob/4eb6f8bafb645c8b4e41524d7dc968bf5c60afb1/light-theme.html) (` ``` ```html expandable theme={"system"}

``` Your merchant ID which is of the format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` [Find it here](https://dashboard.sezzle.com/merchant/settings/business). Renders the page design in dark or light mode Available options: `dark`, `light` Controls the translation of the page content Available options: `en`, `fr` , `es` # AI Assistance Source: https://docs.sezzle.com/docs/guides/ai-assistance All of our documentation pages are hosted in a variety of markdown formats to make it easier for you to feed our docs into large language models (LLMs) for specific information retrieval. ## Supported formats We support industry standards such as [/llms.txt](https://llmstxt.org) as well as additional markdown formats. * A markdown file of a structured index of our docs is hosted at [https://docs.sezzle.com/llms.txt](https://docs.sezzle.com/llms.txt). A markdown file of our docs content is hosted at [https://docs.sezzle.com/llms-full.txt](https://docs.sezzle.com/llms-full.txt). # Authorize & Capture Source: https://docs.sezzle.com/docs/guides/auth-and-capture Merchants integrating Sezzle into their eCommerce platform can choose between two payment settings: `Authorize Only` or `Authorize and Capture`. This page provides a detailed explanation of the differences between these options to help you select the best setting for your needs. ### **Authorize Only** * Payment will only be automatically authorized, not captured, after a successful checkout * In the History section of order details, the `Captured` field displays 0, and `Not Captured` displays the order amount * If `Authorize Only` is set, you must capture the order amount manually before the auth is expired in order to mark the payment as paid ### **Authorize and Capture** * Payment is captured automatically after a successful checkout. * In the `History`section of order details, the `Captured` field displays the order amount, and `Not Captured` displays 0 ### Notes * The default authorization expiration is 30 minutes for all merchants except Shopify, whose default is 7 days * You can extend this up to a maximum of 7 days * Once the authorization expires, capturing is denied, and any uncaptured amount is released * If the order total is not captured before expiration, the order is deleted * Payment is considered paid only when the amount is captured * If the order amount shows `Not Captured` and the `Captured` value in the `History` section of the Merchant Dashboard is 0, the order amount has not been captured * If the amount remains uncaptured before the authorization expires, the order will be deleted ### How to Change Authorization Expiration in Merchant Dashboard 1. Log in to your Merchant Dashboard account 2. Go to the `Settings` > `Payment Captures` > `Authorization Expiration Period` and click `update` 3. Set the value for days, hours, and minutes and click `confirm` # Using Direct Javascript SDK Source: https://docs.sezzle.com/docs/guides/direct/integration The Javascript SDK can be used for a simple, lightweight integration, but it also includes an in-context mode which will host the Sezzle checkout in a modal iframe or pop-up window. Create checkouts and capture payments with Sezzle. Checkout in an iframe, pop-up window, or redirect to Sezzle. Handle payment success, failure, or cancel with your Sezzle 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 direct JavaScript SDK is to configure a new Checkout object. ### Configuration Options ```javascript theme={"system"} const checkoutSdk = new Checkout({ mode: string, publicKey: string, apiMode: string, apiVersion: string, }); ``` ```javascript theme={"system"} const checkoutSdk = new Checkout({ mode: "popup", publicKey: "sz_pub_...", apiMode: "sandbox", apiVersion: "v2", }); ``` 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 a better fit for manual integrations 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` Sezzle Checkout SDK Version Available options: `v2` ## Payment Option This section covers how to present Sezzle as a payment method at checkout. Depending on your webpage's design, you might wish to display Sezzle as an alternative payment method (APM) button, a radio option in a list of payment methods, and/or as an alternative submission button. Below are some examples of how to implement the front-end component. If you wish to use a different design from the options displayed below, please refer to our [Co-Branded Guidelines](https://sezzle.com/brand-assets/) for Approved Messaging and Sezzle logo acceptable use. ### Sezzle in Payment Methods Table Below is an example of Sezzle as a payment method radio.

*This example snippet is for informational use only. Please follow the established HTML format of your existing payment methods.* ```html theme={"system"}

Buy Now, Pay Later

``` ### Sezzle Button The button option is available as a component of this SDK library. It is comprised of two parts: the configurable element plcaeholder and the render function. #### 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. Sezzle as a button alongside other APMs Sezzle as a Submit button as alternative to default button ```html theme={"system"}

``` ```html theme={"system"}

``` Text to appear inside the button. Use `%%logo%%` inside the text to display the Sezzle image The theme corresponds to your site's background color. If `theme`: `dark`, the button will be white with dark text. Else, the button will be dark purple with white text. Available options: `dark`, `light` 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 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 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: { order: { intent: "AUTH", reference_id: "543645yg5tg5675686", description: "sezzle-store - #12749253509255", order_amount: { amount_in_cents: 10000, currency: "USD", }, }, }, }); }, onComplete: function (response) { alert("Completed transaction. Capture started."); checkoutSdk .capturePayment(response.data.order_uuid, { capture_amount: { amount_in_cents: 10000, currency: "USD", }, partial_capture: false, }) .then((r) => { console.log(r); }); }, 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 theme={"system"} checkoutSdk.startCheckout({ checkout_payload: { order: { intent: string, reference_id: string, description: string, order_amount: { amount_in_cents: integer, currency: string, }, }, }, }); ``` ```javascript theme={"system"} checkoutSdk.startCheckout({ checkout_payload: { order: { intent: "AUTH", reference_id: "543645yg5tg5675686", description: "sezzle-store - #12749253509255", order_amount: { amount_in_cents: 10000, currency: "USD", }, }, }, }); ``` The order for this session If your checkout flow requires the user to confirm their checkout on your site after being approved by Sezzle, use “AUTH” as your intent. If you prefer the checkout be captured immediately, use “CAPTURE”. Available options: `AUTH`, `CAPTURE` Your reference ID for this order (must contain only alphanumeric characters, dashes (-), and underscores (\_)) Your description for this order The total amount of the order The amount of the item in cents The 3 character currency code as defined by ISO 4217 Alternatively, start checkout by URL: ```javascript theme={"system"} checkout.startCheckout({ checkout_url: "https://checkout.sezzle.com/?id=example", }); ``` Start checkout should be implemented in the checkout `onClick` handler. There are two methods for hosting a checkout. **Use a checkout payload as detailed in the Session Object** * The cancel and complete URLs are not required for `iframe` and `popup` mode. **Use an existing checkout URL** * The `mode` used when configuring the SDK checkout must match the `checkout_mode` when [creating a session](/docs/api/core/sessions/postv2session). * The parent window `origin` must be provided in the cancel and complete urls when the `checkout_mode` is `iframe` or `popup`. **Customer Tokenization** This is not supported in the `onComplete` event. To receive a customer UUID, subscribe to the [customer.tokenized](/docs/api/core/webhooks/postv2webhooks#valid-webhook-events) event. ### Checkout completed by Payload ```javascript theme={"system"} function onCompleteHandler(event) { var data = event.data || Object.create(null); console.log("session data:", data.session_uuid, data.order_uuid); } checkout.init({ onComplete: onCompleteHandler, }); ``` ### Checkout completed by URL ```javascript theme={"system"} function onCompleteHandler(event) { var data = event.data || Object.create(null); console.log("checkout data:", data.checkout_uuid); } checkout.init({ onComplete: onCompleteHandler, }); ``` ### Capture Payment Capturing an order is not required if the `CAPTURE` intent was used when creating the checkout. ```javascript theme={"system"} var payload = { capture_amount: { amount_in_cents: integer, currency: string, }, }; checkout.capturePayment(data.order_uuid, payload); ``` ```javascript theme={"system"} var payload = { capture_amount: { amount_in_cents: 5000, currency: "USD", }, }; checkout.capturePayment(data.order_uuid, payload); ``` The capture payment method requires two parameters, the `order_uuid` and the payload as detailed in the [Capture Amount By Order Object](/docs/api/core/orders/postv2capturebyorder). The amount to capture on this order The amount in cents The 3 character currency code as defined by ISO 4217 ## Installment Plan ```javascript theme={"system"} const checkout = new Checkout({}); checkout.getInstallmentPlan(1000); ``` ```json theme={"system"} { "schedule": string, "totalInCents": integer, "installments": [ { "installment": integer, "amountInCents": integer, "dueDate": string } ] } ``` ```json theme={"system"} { "schedule": "bi-weekly", "totalInCents": 1000, "installments": [ { "installment": 1, "amountInCents": 250, "dueDate": "2020-10-14" }, { "installment": 2, "amountInCents": 250, "dueDate": "2020-10-28" }, { "installment": 3, "amountInCents": 250, "dueDate": "2020-11-11" }, { "installment": 4, "amountInCents": 250, "dueDate": "2020-11-25" } ] } ``` Payment cadence for installment plan Total order amount in cents Breakdown of each payment due Number of installment in series Installment amount in cents Due date of the installment This function will provide the installment details based on an amount in cents. An existing [checkout](#checkout-initialization) can be used, or a `checkout` without any configuration can also be used to quickly get installment details. # Introduction Source: https://docs.sezzle.com/docs/guides/direct/introduction ## Direct Integration Order Flow Overview Pn

1. Request Payment Session Creation * The Merchant Server sends a request to the Sezzle API to create a payment session for the customer’s order, including details like the order amount, items, and customer information. 2. Generate Session and Redirect URL * The Sezzle API processes the request, creates a session linked to the order, and generates a redirect URL for the customer to access the Sezzle UI for payment processing. 3. Receive Redirect URL from Sezzle API * The Sezzle API sends the generated redirect URL to the Merchant Server, allowing the merchant to proceed with customer redirection. 4. Redirect Customer to Sezzle UI * Using the redirect URL, the Merchant Server directs the customer to the Sezzle UI to complete the payment process. 5. Process Customer Checkout in Sezzle UI * The customer reviews the order in the Sezzle UI and completes the checkout. * Sezzle assesses the customer’s financing eligibility (e.g., via a credit check), approving or denying the transaction. * If denied, the customer must use an alternative payment method. 6. Redirect Customer Back to Merchant Site (Optional) * After checkout (approved or denied), Sezzle redirects the customer to the Merchant Site. * The merchant may display a confirmation page showing the order status (e.g., “Order Confirmed” or “Payment Failed”). * This step is optional based on the merchant’s preference. 7. Request Fund Capture * Upon payment approval, the Merchant Server sends a request to the Sezzle API to capture the order funds, either in full or partially (e.g., for partial shipments). 8. Receive Transaction Status from Sezzle API * The Sezzle API processes the capture request and returns the transaction status to the Merchant Server. * The status indicates whether the funds were captured successfully or if issues occurred (e.g., invalid amount and/or currency etc.). * The merchant updates their system and notifies the customer accordingly. # Manual Integration Source: https://docs.sezzle.com/docs/guides/direct/manual The [Javascript SDK](./integration) is a great way to get started but if not available for your implementation you can perform all necessary actions on your own. ## Quick Start Guide 1. Use API keys to obtain an [authentication](/docs/api/core/authentication/postauthentication) token 2. Create a [session](/docs/api/core/sessions/postv2session) with an order object 3. Redirect user to Sezzle checkout URL 4. User completes Sezzle checkout 5. Sezzle redirects user back to merchant complete URL 6. Manage the order with the [Orders API](/docs/api/core/orders/getv2order) 7. Subscribe to all necessary [Webhook Events](/docs/api/core/webhooks/postv2webhooks) # Configuration Source: https://docs.sezzle.com/docs/guides/express/express-checkout The Sezzle Express checkout button is a powerful tool for custom platform merchants. Integrated directly into the cart page, the button allows shoppers to select Sezzle as their payment method with a single click, leveraging their Sezzle account for a seamless payment experience. This feature is designed to reduce cart abandonment, increase conversion rate, and enhance customer satisfaction. ## Installation ### Include SDK code Include the following script in the `` section of the page. ```html theme={"system"} ``` ### Checkout Configuration #### Configuration Options ```javascript theme={"system"} const checkoutSdk = new Checkout({ mode: string, publicKey: string, apiMode: string, apiVersion: string, }); ``` ```javascript theme={"system"} const checkoutSdk = new Checkout({ mode: "popup", publicKey: "sz_pub_...", apiMode: "live", apiVersion: "v2", }); ``` 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` Sezzle Checkout SDK Version Available options: `v2` ### 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"} await 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 expandable theme={"system"} checkoutSdk.init({ onClick: function () { event.preventDefault(); checkoutSdk.startCheckout({...}); }, onComplete: function (response) { console.log(response.data); }, onCancel: function () { alert("Transaction cancelled."); }, onFailure: function () { alert("Transaction failed."); }, onCalculateAddressRelatedCosts: async function ( shippingAddress, order_uuid ) { // Call authentication endpoint const response = await fetch( "https://gateway.sezzle.com/v2/authentication", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ public_key: string, private_key: string, }), } ); const data = await response.json(); const token = data.token; const updateResponse = await fetch( `https://gateway.sezzle.com/v2/order/${order_uuid}/checkout`, { method: "PATCH", headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}`, }, body: JSON.stringify({ currency_code: string, address_uuid: shippingAddress.uuid, shipping_options: [ { name: string, description: string, shipping_amount_in_cents: integer, tax_amount_in_cents: integer, final_order_amount_in_cents: integer } ] }), } ); const updateStatus = updateResponse.ok; return { ok: updateStatus, }; }, }); ``` ```javascript expandable theme={"system"} checkoutSdk.init({ onClick: function () { event.preventDefault(); checkoutSdk.startCheckout({ checkout_payload: { // "cancel_url":{ // "href": "http://localhost:44300/demo/v2checkout.html" // }, // "complete_url":{ // "href": "http://localhost:44300/demo/v2checkout.html" // }, express_checkout_type: "multi-step", order: { intent: "AUTH", reference_id: "543645yg5tg5675686", description: "sezzle-store - #12749253509255", requires_shipping_info: true, items: [ { name: "widget", sku: "sku123456", quantity: 1, price: { amount_in_cents: 1000, currency: "USD", }, }, ], discounts: [ { name: "20% off", amount: { amount_in_cents: 1000, currency: "USD", }, }, ], metadata: { location_id: "123", store_name: "Downtown Minneapolis", store_manager: "Jane Doe", }, order_amount: { amount_in_cents: 10000, currency: "USD", }, }, }, }); }, onComplete: function (response) { alert("Completed transaction. Capture started."); checkoutSdk .capturePayment(response.data.order_uuid, { capture_amount: { amount_in_cents: 10000, currency: "USD", }, partial_capture: false, }) .then((r) => { console.log(r); }); }, onCancel: function () { alert("Transaction cancelled."); }, onFailure: function () { alert("Transaction failed."); }, onCalculateAddressRelatedCosts: async function ( shippingAddress, order_uuid ) { // Call authentication endpoint const response = await fetch( "https://gateway.sezzle.com/v2/authentication", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ private_key: sz_pr_... public_key: sz_pub_... }), } ); const data = await response.json(); const token = data.token; const updateResponse = await fetch( `https://gateway.sezzle.com/v2/order/${order_uuid}/checkout`, { method: "PATCH", headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}`, }, body: JSON.stringify({ currency_code: "USD", address_uuid: shippingAddress.uuid, shipping_options: [ { name: "Standard Shipping", description: "3-5 business days", shipping_amount_in_cents: 2000, tax_amount_in_cents: 3000, final_order_amount_in_cents: 10200 }, { name: "Express Shipping", description: "1-2 business days", shipping_amount_in_cents: 2000, tax_amount_in_cents: 3000, final_order_amount_in_cents: 10200 } ] }), } ); const updateStatus = updateResponse.ok; return { ok: updateStatus, }; }, }); ``` 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. See [capturePayment](#capture-payment) section for payload options. 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. Required if `express_checkout_type` is `single-step` or `multi-step`. Once shopper has provided shipping address via Sezzle express checkout, this function should return tax and shipping costs to Sezzle. #### Checkout Initialization ```javascript expandable theme={"system"} checkoutSdk.startCheckout({ checkout_payload: { // "cancel_url":{ // "href": string // }, // "complete_url":{ // "href": string // }, express_checkout_type: string, order: { intent: string, reference_id: string, description: string, requires_shipping_info: boolean, items: [ { name: string, sku: string, quantity: integer, price: { amount_in_cents: integer, currency: string, }, }, ], discounts: [ { name: string, amount: { amount_in_cents: integer, currency: string, }, }, ], metadata: { some_property: string, some_other_property: string }, order_amount: { amount_in_cents: integer, currency: string, }, }, }, }); ``` ```javascript theme={"system"} checkoutSdk.startCheckout({ checkout_payload: { // "cancel_url":{ // "href": "http://localhost:44300/demo/v2checkout.html" // }, // "complete_url":{ // "href": "http://localhost:44300/demo/v2checkout.html" // }, express_checkout_type: "multi-step", order: { intent: "AUTH", reference_id: "543645yg5tg5675686", description: "sezzle-store - #12749253509255", requires_shipping_info: true, items: [ { name: "widget", sku: "sku123456", quantity: 1, price: { amount_in_cents: 1000, currency: "USD", }, }, ], discounts: [ { name: "20% off", amount: { amount_in_cents: 1000, currency: "USD", }, }, ], metadata: { location_id: "123", store_name: "Downtown Minneapolis", store_manager: "Jane Doe", }, order_amount: { amount_in_cents: 10000, currency: "USD", }, }, }, }); ``` The HTTP request information used to redirect the customer in the case of a cancellation The URL used when redirecting a customer The HTTP request information used to redirect the customer upon completion of the session The URL used when redirecting a customer * `single-step`: only one shipping method exists, or only use default shipping method for Sezzle express checkout flow * `multi-step`: allow the user to select from merchant-supported shipping methods * `no-shipping`: purchase contains no shippable items and shopper does not have option to select, such as digital download or buy online pick up in store (BOPIS) For `single-step and `multi-step`, `requires\_shipping\_info`must be`true`. For `no-shipping`, `requires\_shipping\_info`must be`false\` Available options: `single-step`, `multi-step`, `no-shipping` The order for this session If your checkout flow requires the user to confirm their checkout on your site after being approved by Sezzle, use “AUTH” as your intent. If you prefer the checkout be captured immediately, use “CAPTURE”. Available options: `AUTH`, `CAPTURE` Your reference ID for this order (must contain only alphanumeric characters, dashes (-), and underscores (\_)) Your description for this order Flag to indicate if you would like us to collect shipping information for this checkout from the customer. If omitted, defaults to false. If `express_checkout_type` is `single-step` or `multi-step`, `requires_shipping_info` must be `true`. For `express_checkout_type`: `no-shipping` and standard checkout, use `false` 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 The discounts applied to this order. Must be included in total The description of the discount A price object The amount of the item in cents The 3 character currency code as defined by ISO 4217 Object for any custom data you want to submit with the checkout. You are not limited to the key-value pairs shown in the example, and you may use any key-value pairs you like Custom metadata field Custom metadata field The taxes applied to this order. Must be included in the total. If `express_checkout_type` is `single-step` or `multi-step`, this can be omitted - it will be provided after shopper confirms shipping address. The amount of the item in cents The 3 character currency code as defined by ISO 4217 The total amount of the order The amount of the item in cents The 3 character currency code as defined by ISO 4217 Start checkout should be implemented in the checkout `onClick` handler. There are two methods for hosting a checkout. **Use a checkout payload as detailed in the Session Object** * The cancel and complete URLs are not required for `iframe` and `popup` mode. **Use an existing checkout URL** * The `mode` used when configuring the SDK checkout must match the `checkout_mode` when [creating a session](/docs/api/core/sessions/postv2session). * The parent window `origin` must be provided in the cancel and complete urls when the `checkout_mode` is `iframe` or `popup`. **Customer Tokenization** This is not supported in the `onComplete` event. To receive a customer UUID, subscribe to the [customer.tokenized](/docs/api/core/webhooks/postv2webhooks#valid-webhook-events) event. #### Capture Payment Capturing an order is not required if the `CAPTURE` intent was used when creating the checkout. ```javascript theme={"system"} checkoutSdk .capturePayment(response.data.order_uuid, { capture_amount: { amount_in_cents: integer, currency: string, }, partial_capture: boolean, }) .then((r) => { console.log(r); }); ``` ```javascript theme={"system"} checkoutSdk .capturePayment(response.data.order_uuid, { capture_amount: { amount_in_cents: 10000, currency: "USD", }, partial_capture: false, }) .then((r) => { console.log(r); }); ``` The amount to capture on this order The amount in cents The 3 character currency code as defined by ISO 4217 #### onCalculateAddressRelatedCosts For security purposes, authentication and checkout update must originate from merchant's back-end code. 1. Get authentication token * Call the [authentication](/docs/api/core/authentication/postauthentication) endpoint to obtain a bearer token * You should have already set this up in your back-end for the standard integration * Instead of pointing directly to Sezzle as in the below example, you can re-use your existing function 2. Update the order * Call the Update Checkout endpoint to provide Sezzle with shipping option(s) and final tax and shipping amount based on shopper's shipping address * See `Options` tab below for more details Once `shipping_options` have been provided to Sezzle for a checkout, they cannot be edited unless the shopper changes their shipping address. ```javascript expandable theme={"system"} onCalculateAddressRelatedCosts: async function ( shippingAddress, order_uuid ) { // Call authentication endpoint const response = await fetch( yourBackendAuthenticationURL, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ public_key: string, private_key: string, }), } ); const data = await response.json(); const token = data.token; const updateResponse = await fetch( yourBackendUpdateOrderURL, { method: "PATCH", headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}`, }, body: JSON.stringify({ currency_code: string, address_uuid: shippingAddress.uuid, shipping_options: [ { name: string, description: string, shipping_amount_in_cents: integer, tax_amount_in_cents: integer, final_order_amount_in_cents: integer } ] }), } ); const updateStatus = updateResponse.ok; return { ok: updateStatus, }; }, ``` ```javascript expandable theme={"system"} onCalculateAddressRelatedCosts: async function ( shippingAddress, order_uuid ) { // All this must be done inside your backend endpoint and this should be replaced with your endpoint communication logic // Call authentication endpoint const response = await fetch( `https://sandbox.gateway.sezzle.com/v2/authentication`, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ private_key: sz_pr_..., public_key: sz_pub_..., }), } ); const data = await response.json(); const token = data.token; // Calculate your shipping options based on the provided shippingAddress const shipping_options = [ { name: "Standard Shipping", description: "3-5 business days", shipping_amount_in_cents: 1000, tax_amount_in_cents: 500, final_order_amount_in_cents: 11500 }, { name: "Express Shipping", description: "1-2 business days", shipping_amount_in_cents: 2000, tax_amount_in_cents: 1000, final_order_amount_in_cents: 13000 } ] // Update your checkout with the calculated shipping options const updateResponse = await fetch( `https://sandbox.gateway.sezzle.com/v2/order/{order_uuid}/checkout`, { method: "PATCH", headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}`, }, body: JSON.stringify({ currency_code: "USD", address_uuid: shippingAddress.uuid, shipping_options, }), } ); const updateStatus = updateResponse.ok; return { ok: updateStatus, }; } ``` The 3 character currency code as defined by ISO 4217 The address UUID for the order The available shipping options for the order, in order of recommendation/preference * If `express_checkout_type` is `multi-step` but only one method is provided, user experience will follow `single-step` flow from this point * If `express_checkout_type` is `single-step` but multiple methods are provided, the shopper will be presented with an error. * If `express_checkout_type` is `multi-step` or `single-step` and no methods are provided, the shopper will be asked to review their shipping address and try again. The name of the shipping method The description of the shipping method, such as number of business days The shipping amount in cents for the order The tax amount in cents for the order The final total amount in cents for the order ##### Response ```json theme={"system"} { ok: boolean, error: { code: string } } ``` ```json theme={"system"} { ok: false, error: { code: "merchant_unsupported_shipping_address" } } ``` Available options: `merchant_unsupported_shipping_address`, `merchant_error` `merchant_unsupported_shipping_address` indicates that the merchant does not support the shipping address provided. `merchant_error` is generic error returned by the merchant when something goes wrong on their end. # Introduction Source: https://docs.sezzle.com/docs/guides/express/introduction Install the Sezzle Express Checkout button to increase conversion rates and enhance customer satisfaction. Sezzle Express Checkout is only available for direct integration and [WooCommerce](/docs/plugins/woocommerce) merchants. ## Shopper Experience Sezzle shoppers can skip the manual entry on the merchant checkout by using the contact info and card details on their Sezzle account. Simply sign in and confirm shipping address, avoiding up to 20 fields. Express Overview Shopper
Pn

Shoppers click the Sezzle Express button to visit Sezzle’s checkout page. The shopper signs in to Sezzle and confirms their shipping address. The shopper selects their desired shipping method. The shopper selects their preferred installment plan. The shopper’s details are sent to the merchant. The express checkout process minimizes friction by eliminating the need for shoppers to manually enter shipping and payment details, especially for returning Sezzle shoppers with saved information. The prefilled data, enabled by the merchant’s API integration, creates a seamless experience that reduces abandoned carts and boosts sales. ### Compare to Standard Checkout Flow Standard Shopper
Pn

Without the Sezzle checkout button or prefilled information, the checkout process involves multiple steps, which can lead to cart abandonment due to complexity: 1. Add Items to Cart and Proceed to Checkout * Shoppers select their desired products and initiate the checkout process on the merchant’s website 2. Enter Contact Information * Shoppers manually input their name, email, and phone number 3. Enter Shipping Details * Shoppers manually input their address 4. Select Shipping Method * Shoppers manually select their shipping method 5. Select Sezzle as Payment Method * Shoppers choose Sezzle from the available payment options and are redirected to Sezzle’s checkout page 6. Sign In and Complete Purchase * On Sezzle’s site, shoppers sign in or create an account, confirm their payment plan (e.g., 25% upfront, three installments), and finalize the order This multi-step process can deter shoppers, especially those who find entering information tedious or who abandon their carts due to lengthy forms. ## How It Works Express Overview Simple
Pn

## FAQs No. Express Checkout is available to all Sezzle partners at no extra cost. You’ll just need a Merchant ID (MID) to activate it. Sezzle Express Checkout is only available for direct integration and [**WooCommerce**](https://docs.sezzle.com/docs/plugins/woocommerce) merchants. The button can be placed on product pages, the cart page, or within checkout to drive faster conversions. Our recommendation is to configure the button in all 3 locations to encourage quick and seamless purchases and to provide the best possible shopper experience. Your website or app must already be set up to accept Sezzle payments before enabling Express Checkout. Implementation is done via direct integration. Follow our[ Express Checkout Quick Guide](https://docs.sezzle.com/docs/guides/express/quick-guide) for step-by-step instructions. The implementation process should take no longer than 3-5 days. Only essential order and customer information is used. This keeps the process secure, efficient, and privacy-first. Yes. It can be offered alongside other payment buttons without disrupting your checkout flow. Yes. The button’s style can be adjusted to align with your brand. Express Checkout is available in all regions where Sezzle Payments are offered. # Quick Guide Source: https://docs.sezzle.com/docs/guides/express/quick-guide Express Checkout option is only available for direct integration and [WooCommerce](/docs/plugins/woocommerce) merchants. ## Installation 1. Import Library * Copy this script to the `` of your site code ```html theme={"system"} ``` 2. Configure SDK * Configure [Express Checkout](./express-checkout#configuration-options) ```diff theme={"system"} const checkoutSdk = new Checkout({ mode: "popup", + publicKey: `${yourSezzleAPIKey}`, apiMode: "live", apiVersion: "v2", }); ``` 3. Install Button * Copy this placeholder element to where you wish the button to render on the page * [See here for customization options](./express-checkout#sezzle-button-configuration) ```html theme={"system"}

``` * Load the button using Javascript ```javascript theme={"system"} await checkoutSdk.renderSezzleButton("sezzle-smart-button-container"); ``` 4. Configure the [event listeners](./express-checkout#configuration-options) ```diff expandable theme={"system"} checkoutSdk.init({ onClick: function () { console.log("onClick"); event.preventDefault(); checkoutSdk.startCheckout({ checkout_payload: { express_checkout_type: "multi-step", is_express_checkout: true, order: { intent: "AUTH", reference_id: "543645yg5tg5675686", description: "sezzle-store - #12749253509255", requires_shipping_info: true, items: [ { name: "widget", sku: "sku123456", quantity: 1, price: { amount_in_cents: 1000, currency: "USD", }, }, ], discounts: [ { name: "20% off", amount: { amount_in_cents: 1000, currency: "USD", }, }, ], metadata: { location_id: "123", store_name: "Downtown Minneapolis", store_manager: "Jane Doe", }, order_amount: { amount_in_cents: 10000, currency: "USD", }, }, }, }); }, onComplete: function (response) { alert("Completed transaction. Capture started."); checkoutSdk .capturePayment(response.data.order_uuid, { capture_amount: { amount_in_cents: 10000, currency: "USD", }, partial_capture: false, }) .then((r) => { console.log(r); }); }, onCancel: function () { console.log("onCancel"); alert("Transaction cancelled."); }, onFailure: function () { console.log("onFailure"); alert("Transaction failed."); }, onCalculateAddressRelatedCosts: async function ( shippingAddress, order_uuid ) { // All this must be done inside your backend endpoint and this should be replaced with your endpoint communication logic // Call authentication endpoint const response = await fetch( `https://sandbox.gateway.sezzle.com/v2/authentication`, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ private_key: sz_pr_..., public_key: sz_pub_..., }), } ); const data = await response.json(); const token = data.token; // Calculate your shipping options based on the provided shippingAddress const shipping_options = [ { name: "Standard Shipping", description: "3-5 business days", shipping_amount_in_cents: 1000, tax_amount_in_cents: 500, final_order_amount_in_cents: 11500 }, { name: "Express Shipping", description: "1-2 business days", shipping_amount_in_cents: 2000, tax_amount_in_cents: 1000, final_order_amount_in_cents: 13000 } ] // Update your checkout with the calculated shipping options const updateResponse = await fetch( `https://sandbox.gateway.sezzle.com/v2/order/{order_uuid}/checkout`, { method: "PATCH", headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}`, }, body: JSON.stringify({ currency_code: "USD", address_uuid: shippingAddress.uuid, shipping_options, }), } ); const updateStatus = updateResponse.ok; return { ok: updateStatus, }; }, }); ``` ## Example ```html theme={"system"} Sezzle Express Checkout Test

Sezzle Test

``` # Sezzle Banner Source: https://docs.sezzle.com/docs/guides/home-banner Add a Sezzle banner to your online store to let customers know they can shop now and pay later. Frame1456677764(1) Pn

## Installation Select the implementation that fits your needs: ### Shopify: * [Asset from CDN](#from-cdn) * [Asset as Local File](#local-file) * [Plain HTML](#install-as-html) ### All Platforms: * [Asset from CDN](#from-cdn-2) * [Asset as Local File](#local-file-2) * [Plain HTML](#install-as-html-2) *** ## Shopify ### Install as Asset #### From CDN 1. Log in to your Shopify Admin 2. Go to `Online Store` > `Themes` 3. Next to the applicable theme, click `Actions` then `Edit Code` 4. Paste the following snippet into the `sections/header.liquid` file where the banner should appear, update the `merchantUUID` value, then click `Save` * Note: this is typically below the `header` or `sticky-header` closing tag. Open the file, then search (Cmd+F or Ctrl+F) for the word "sticky-header" ```html theme={"system"} {{ "//checkout-sdk.sezzle.com/sezzle-home-banner.min.js" | script_tag }} ``` ```html theme={"system"} {{ "//checkout-sdk.sezzle.com/sezzle-home-banner.min.js" | script_tag }} ``` Your merchant ID which is of the format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` [Find it here](https://dashboard.sezzle.com/merchant/settings/business). Renders the page design with dark purple or black background Available options: `indigo`, `black` The placeholder or parent container where the banner should appear. Should be a unique `.class-name` or `#id-name` #### Local File 1. Clone/pull down the [Static-Widgets](https://github.com/sezzle/static-widgets/) project, then run `npm run build-banner` 2. Log in to your Shopify Admin 3. Go to `Online Store` > `Themes` 4. Next to the applicable theme, click `Actions` then `Edit Code` 5. Scroll to the Assets folder, then click `Add A New Asset` 6. Click `Create a Blank File`, name the section `sezzle-home-banner`, select `.js` as the file type, then click `Add Asset` 7. In the Assets folder, select the asset you just created (you may need to scroll, files are not in alphabetical order). 8. Overwrite the asset template with the code contents here: `static-widgets/build/sezzle-home-banner.js`, then click `Save`. 9. Paste the following snippet into the `sections/header.liquid` file where the banner should appear, update the `merchantUUID` value, then click `Save`: * Note: this is typically below the `header` or `sticky-header` closing tag. Open the file, then search (Cmd+F or Ctrl+F) for the word "sticky-header" ```html theme={"system"} {{ "sezzle-home-banner.js" | asset_url | script_tag }} ``` ```html theme={"system"} {{ "sezzle-home-banner.js" | asset_url | script_tag }} ``` Your merchant ID which is of the format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` [Find it here](https://dashboard.sezzle.com/merchant/settings/business). Renders the page design with dark purple or black background Available options: `indigo`, `black` The placeholder or parent container where the banner should appear. Should be a unique `.class-name` or `#id-name` ### Install as HTML 1. Log in to your Shopify Admin 2. Go to `Online Store` > `Themes` 3. Next to the applicable theme, click `Actions` then `Edit Code` 4. Paste the code snippet [here](https://github.com/sezzle/static-widgets/tree/production/src/sezzle-home-banner/sezzle-home-banner.html) into the `sections/header.liquid` file where the banner should appear, then click `Save` * Note: this is typically below the `header` or `sticky-header` closing tag. Open the file, then search (Cmd+F or Ctrl+F) for the word "sticky-header" #### Customization * Update the wrapper element's class name to the theme color you desire (indigo or black) * Update the Learn More href URL to point to your own [How Sezzle Works](/docs/guides/about-sezzle) page, if applicable ## Other Platforms ### From CDN Paste the following where the banner should appear, such as below `` and update the `merchantUUID` value ```html theme={"system"} ``` ```html theme={"system"} ``` Your merchant ID which is of the format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` [Find it here](https://dashboard.sezzle.com/merchant/settings/business). Renders the page design with dark purple or black background Available options: `indigo`, `black` The placeholder or parent container where the banner should appear. Should be a unique `.class-name` or `#id-name` ### Local File Clone/pull down the [Static-Widgets](https://github.com/sezzle/static-widgets/) project, then run `npm run build-banner` Create a new .js file and populate it with the code contents from here: `static-widgets/build/sezzle-home-banner.js` Paste the following where the banner should appear, such as below ``, then update the file path and `merchantUUID` value ```html theme={"system"} ``` ```html theme={"system"} ``` Your merchant ID which is of the format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` [Find it here](https://dashboard.sezzle.com/merchant/settings/business). Renders the page design with dark purple or black background Available options: `indigo`, `black` The placeholder or parent container where the banner should appear. Should be a unique `.class-name` or `#id-name` ### Install as HTML Paste the code snippet [here](https://github.com/sezzle/static-widgets/tree/production/src/sezzle-home-banner/sezzle-home-banner.html) where the banner should appear, such as below `` #### Customization * Update the wrapper element's class name to the theme color you desire (indigo or black) * Update the Learn More href URL to point to your own [How Sezzle Works](/docs/guides/about-sezzle) page, if applicable # In-Store Source: https://docs.sezzle.com/docs/guides/in-store The Sezzle POS Checkout API allows merchants to send a Sezzle Checkout link to customers via text or email and receive real-time payment updates on their POS system upon checkout completion. ## Customer Experience This is what the customer sees if they click the text message or email link. The shopper enters their phone number and OTP. The shopper adds a payment method. The shopper selects their preferred installment plan. The shopper completes their Sezzle order. ### Direct API Checkout 1. Merchant creates a [session](/docs/api/core/sessions/postv2session) * Set order `intent` to `AUTH` * The customer checkout is texted or emailed as set in `send_checkout_url` 2. Sezzle returns order uuid and checkout URL 3. Customer receives Sezzle URL via text or email to check out 4. Customer completes the Sezzle checkout 5. Merchant receives order-complete notification * You can either [get order details](/docs/api/core/orders/getv2order) or subscribe to [webhooks](/docs/api/core/webhooks/postv2webhooks) 6. (optional) Update the [order reference](https://docs.sezzle.com/docs/guides/virtual/automated#set-order-reference-id) 7. [Capture](/docs/api/core/orders/postv2capturebyorder) the payment 8. (optional) Expire the checkout manually * [Delete the checkout](/docs/api/core/orders/deletev2deletecheckoutbyorder) if the customer has not completed the checkout and the merchant has canceled the order 9. (optional) [Refund](/docs/api/core/orders/postv2refundbyorder) the order # Android SDK Source: https://docs.sezzle.com/docs/guides/mobile/android This guide walks you through integrating the Sezzle Android SDK into your app. By the end, your app will display Sezzle promotional messaging on product pages and launch Sezzle checkout. ### Prerequisites * Android 6.0+ (API 23), compileSdk 35+ * Kotlin or Java * A Sezzle merchant account with your Public API Key * A backend server to capture payments after checkout A working example app is included in the SDK repo at example/. It demonstrates all widget variants and both checkout modes. ## 1. Installation Add to your app module's `build.gradle.kts`: ```kotlin theme={"system"} dependencies { implementation("com.sezzle:sezzle-merchant-sdk:1.2.3") } ``` Add to your app module's `build.gradle`: ```groovy theme={"system"} dependencies { implementation 'com.sezzle:sezzle-merchant-sdk:1.2.3' } ``` The SDK is published on Maven Central. No additional repository configuration is needed. **Requirements:** Android 6.0+ (API 23), compileSdk 35+ ## 2. Configuration Initialize the SDK once at app startup in your `Application` class: ```kotlin theme={"system"} import com.sezzle.sdk.SezzleSDK import com.sezzle.sdk.SezzleEnvironment class MyApplication : Application() { override fun onCreate() { super.onCreate() SezzleSDK.configure( publicKey = "sz_pub_your_key_here", environment = SezzleEnvironment.PRODUCTION // use SANDBOX for testing ) } } ``` | Parameter | Type | Default | Description | | ------------- | ------------------- | ------------ | -------------------------------------------- | | `publicKey` | `String` | Required | Your Sezzle public API key | | `environment` | `SezzleEnvironment` | `PRODUCTION` | `SANDBOX` for testing, `PRODUCTION` for live | Never include your **private** API key in the app. The SDK only uses the public key. Use your private key server-side to capture payments. ## 3. Promotional Messaging Add a `SezzlePromotionalView` to your product screen to display installment pricing: ```kotlin theme={"system"} import com.sezzle.sdk.SezzlePromotionalView val promoView = SezzlePromotionalView( context = this, amountInCents = 9999 // $99.99 ) promoView.setPresenter(this) // Activity for modal presentation container.addView(promoView) ``` The widget automatically shows the correct message based on the price and updates when you call: ```kotlin theme={"system"} promoView.update(amountInCents = 14999) // price changed to $149.99 ``` Android Widgets

### All Parameters ```kotlin theme={"system"} SezzlePromotionalView( context: Context, amountInCents: Int, currency: String = "USD", style: SezzlePromotionalStyle = SezzlePromotionalStyle.LIGHT, widgetConfig: SezzleWidgetConfig = SezzleWidgetConfig.DEFAULT ) ``` | Parameter | Type | Default | Description | | --------------- | ------------------------ | --------- | ----------------------------------------------- | | `amountInCents` | `Int` | Required | Product price in cents (e.g., 4999 = \$49.99) | | `currency` | `String` | `"USD"` | ISO 4217 currency code (e.g., `"USD"`, `"CAD"`) | | `style` | `SezzlePromotionalStyle` | `LIGHT` | `LIGHT` for light backgrounds, `DARK` for dark | | `widgetConfig` | `SezzleWidgetConfig` | `DEFAULT` | Controls pricing thresholds and Pay-in-5 | The widget auto-detects dark mode and switches styles automatically. If you want to force a specific style, pass `SezzlePromotionalStyle.LIGHT` or `SezzlePromotionalStyle.DARK` explicitly. ### Widget Configuration All config parameters are **optional** — the widget works out of the box with sensible defaults: | Parameter | Default | Description | | -------------------- | ------------------ | ------------------------------------------------------------------------------- | | `minPriceInCents` | `3500` (\$35) | Minimum price to show the widget | | `maxPriceInCents` | `250000` (\$2,500) | Maximum price for short-term (PI4/PI5) | | `enablePayIn5` | `true` | Show "5 payments" for prices at or above the PI5 threshold | | `pi5MinPriceInCents` | `5000` (\$50) | Price threshold for Pay-in-5 | | `longTermConfig` | `null` (disabled) | Enable long-term monthly payments — set to a `SezzleLongTermConfig` to activate | To customize, pass only the values you want to override: ```kotlin theme={"system"} val config = SezzleWidgetConfig( longTermConfig = SezzleLongTermConfig( minPriceInCents = 25_000 // $250+ shows monthly payments ) ) val promoView = SezzlePromotionalView( context = this, amountInCents = 79900, widgetConfig = config ) ``` ### Custom Promotional Text If you need full control over the UI, use `SezzlePromoDataHandler` to get a styled `SpannableString` with the Sezzle logo inline: ```kotlin theme={"system"} SezzlePromoDataHandler.getMessage( context = this, amountInCents = 9999 ) { spannableString -> myTextView.text = spannableString } ``` ## 4. Checkout ### Build the Checkout Object ```kotlin theme={"system"} val checkout = SezzleCheckout( customer = SezzleCustomer( email = "customer@example.com", firstName = "Jane", lastName = "Doe", phone = "+15551234567", billingAddress = SezzleAddress( street = "123 Main St", city = "Minneapolis", state = "MN", postalCode = "55401", countryCode = "US" ) ), order = SezzleOrder( referenceId = "order-12345", description = "Wireless Earbuds", amount = SezzleAmount(amountInCents = 4599, currency = "USD"), items = listOf( SezzleItem( name = "Wireless Earbuds", sku = "WE-001", quantity = 1, price = SezzleAmount(amountInCents = 3999, currency = "USD") ) ), taxAmount = SezzleAmount(amountInCents = 350, currency = "USD"), shippingAmount = SezzleAmount(amountInCents = 250, currency = "USD") ) ) ``` #### Customer Fields | Field | Required | Description | | ----------------- | -------- | ----------------------------------- | | `email` | Yes | Customer email address | | `firstName` | No | Customer first name | | `lastName` | No | Customer last name | | `phone` | No | Customer phone number | | `dob` | No | Date of birth (`"YYYY-MM-DD"`) | | `billingAddress` | No | Billing address (`SezzleAddress`) | | `shippingAddress` | No | Shipping address (`SezzleAddress`) | | `tokenize` | No | Tokenize customer for future orders | #### Order Fields | Field | Required | Description | | -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `referenceId` | Yes | Your internal order/reference ID | | `description` | No | Order description (defaults to "Mobile SDK Order") | | `amount` | Yes | Total order amount in cents + currency | | `intent` | No | [`AUTH`](/docs/api/core/sessions/postv2session#body-order-intent) (default, capture later from your backend) or `CAPTURE` (auto-capture at checkout completion) | | `items` | No | Line item details | | `discounts` | No | Discount line items (`List`) | | `taxAmount` | No | Tax amount breakdown | | `shippingAmount` | No | Shipping amount breakdown | | `metadata` | No | Custom key-value pairs. The SDK automatically includes `_sdk_platform`, `_sdk_version`, `_device_model`, and `_os_version` — avoid using keys prefixed with `_`. | | `locale` | No | Checkout locale (`EN_US`, `EN_CA`, `FR_CA`) | | `checkoutFinancingOptions` | No | Restrict to specific plans: `FOUR_PAY_BIWEEKLY`, `FOUR_PAY_MONTHLY`, `SIX_PAY_MONTHLY`. Optional — omit to let Sezzle show all eligible plans. | #### Address Fields (`SezzleAddress`) | Field | Description | | ------------- | ------------------------------- | | `name` | Full name | | `street` | Street address line 1 | | `street2` | Street address line 2 | | `city` | City | | `state` | State or province | | `postalCode` | Postal/ZIP code | | `countryCode` | ISO country code (e.g., `"US"`) | | `phone` | Phone number | ### Start Checkout ```kotlin theme={"system"} SezzleSDK.startCheckout( checkout = checkout, activity = this, // ComponentActivity listener = checkoutListener, // SezzleCheckoutListener mode = SezzleCheckoutMode.SYSTEM_BROWSER // or WEB_VIEW ) ``` The `activity` parameter must be a `ComponentActivity` (e.g., `AppCompatActivity`). The SDK uses the Activity Result API internally. ### Handle the Result Implement `SezzleCheckoutListener`: ```kotlin theme={"system"} private val checkoutListener = object : SezzleCheckoutListener { override fun onCheckoutComplete(result: SezzleCheckoutResult) { // For this flow, `result.orderUUID` is populated. // (For the server-driven flow, see Section 8.) result.orderUUID?.let { orderUUID -> // Send orderUUID to your backend to capture payment // POST /v2/order/{orderUUID}/capture Log.d("Sezzle", "Order completed: $orderUUID") } } override fun onCheckoutCancel() { // Customer closed checkout without completing Log.d("Sezzle", "Checkout cancelled") } override fun onCheckoutError(error: SezzleError) { // Handle the error when (error) { is SezzleError.NetworkError -> Log.e("Sezzle", "Network error: ${error.underlying}") is SezzleError.ApiError -> Log.e("Sezzle", "API error ${error.statusCode}: ${error.apiMessage}") is SezzleError.BrowserDismissed -> Log.d("Sezzle", "Browser dismissed") is SezzleError.NotConfigured -> Log.e("Sezzle", "SDK not configured") is SezzleError.InvalidResponse -> Log.e("Sezzle", "Invalid response") } } } ``` After `onCheckoutComplete`, send `result.orderUUID` to your backend server. Your server should call `POST /v2/order/{orderUUID}/capture` using your **private** API key to capture the payment. See the [Orders API](/docs/api/core/orders/postv2capturebyorder) for details. ## 5. WebView Mode By default, checkout opens in Chrome Custom Tabs — a secure browser tab that runs in its own process and shares cookies with Chrome (faster login for returning Sezzle users). To keep the user inside your app, use WebView mode: ```kotlin theme={"system"} SezzleSDK.startCheckout( checkout = checkout, activity = this, listener = checkoutListener, mode = SezzleCheckoutMode.WEB_VIEW ) ``` System Browser

| Mode | Pros | Cons | | ---------------- | ------------------------------------------ | ------------------------------------------ | | `SYSTEM_BROWSER` | Secure, shares Chrome cookies, recommended | Brief context switch | | `WEB_VIEW` | Stays in-app | No cookie sharing, user logs in every time | ## 6. Dark Mode The SDK automatically adapts to the device's appearance setting. The promotional widget, installment modal, and checkout modal all support dark mode. Light Mode

If you need to force a specific style: ```kotlin theme={"system"} val promoView = SezzlePromotionalView( context = this, amountInCents = 9999, style = SezzlePromotionalStyle.DARK // force dark style ) ``` ## 7. Error Handling All errors are delivered via `SezzleCheckoutListener.onCheckoutError(error)`: | Error | When | Suggested Action | | ---------------------------------- | -------------------------------------- | ---------------------------------------------- | | `NotConfigured` | `SezzleSDK.configure()` was not called | Call `configure()` in your `Application` class | | `NetworkError` | No internet, timeout, DNS failure | Show retry option | | `ApiError(statusCode, apiMessage)` | Sezzle API returned an error | Check status code and message | | `BrowserDismissed` | User closed the browser/WebView | Return to product page | | `InvalidResponse` | Unexpected response format | Contact Sezzle support | ## 8. Server-Driven Integration For larger merchants who prefer a fully server-driven integration — no public key on-device, with the backend owning session creation, capture, and refunds — use the alternative `startCheckout` overload introduced in `1.2.0`. ### How it works Your backend creates the checkout session via [`POST /v2/session`](/docs/api/core/sessions/postv2session) with merchant-chosen callback URLs, then hands `order.checkout_url` plus those URLs to the app. The SDK opens the URL, intercepts navigation to your callback URLs, and reports back via `SezzleCheckoutListener.onCheckoutComplete(result)` with the full callback URL — so you can encode your own state in the query string and recover it on completion. ```mermaid theme={"system"} sequenceDiagram participant App as Merchant App participant Backend as Merchant Backend participant SDK as Sezzle SDK participant API as Sezzle API App->>Backend: 1. Request checkout Backend->>API: 2. POST /v2/session (with merchant callback URLs) API-->>Backend: order.uuid + order.checkout_url Backend-->>App: 3. checkout_url + callback URLs App->>SDK: 4. startCheckout(checkoutUrl, completeUrl, cancelUrl, …) SDK-->>App: 5. onCheckoutComplete(result.callbackURL) App->>Backend: 6. Map callback URL state → orderUUID Backend->>API: 7. Capture payment ``` ### Step 1 — Backend creates the session Pick any callback URLs you want — a custom scheme like `yourapp-sezzle://...` or HTTPS deep links. You can encode state in the query string (e.g. `yourapp-sezzle://done?orderRef=12345`) and recover it from the SDK callback. Persist `order.uuid` server-side; the app only needs `order.checkout_url` plus the two callback URLs. **Don't put PII, auth tokens, or anything sensitive in the callback URL query string.** The callback URL is rendered in the browser and may be logged. Use opaque references (a random `orderRef` mapped server-side) — never the customer's email, phone, payment data, or session tokens. Custom URL schemes are also **not exclusive** — another app installed on the device can register the same scheme and intercept the callback. For maximum security in production, use **App Links** (verified HTTPS deep links) on Android — they're tied to a domain you control, so other apps can't claim them. ### Step 2 — App presents checkout ```kotlin theme={"system"} SezzleSDK.startCheckout( checkoutUrl = checkoutUrl, // from order.checkout_url (String — pass through as-is) completeUrl = Uri.parse("yourapp-sezzle://checkout/done"), // matches your server's complete_url.href cancelUrl = Uri.parse("yourapp-sezzle://checkout/cancelled"), // matches your server's cancel_url.href activity = this, listener = checkoutListener, mode = SezzleCheckoutMode.WEB_VIEW // or SYSTEM_BROWSER ) ``` `SezzleSDK.configure(...)` is **not** required for this flow — there's nothing for the SDK to authenticate. ### Step 3 — Read the result ```kotlin theme={"system"} override fun onCheckoutComplete(result: SezzleCheckoutResult) { val callbackURL = result.callbackURL ?: return val orderRef = callbackURL.getQueryParameter("orderRef") // Look up orderRef in your backend, then call /v2/order/{order.uuid}/capture } ``` ### Manifest note for `SYSTEM_BROWSER` mode `SYSTEM_BROWSER` mode opens checkout in Chrome Custom Tabs and routes the redirect back via the OS intent system. The SDK ships an intent-filter for `sezzle-sdk://checkout` only — if you use a custom callback scheme, register an intent-filter for your scheme in your own `AndroidManifest.xml`, pointing at `SezzleRedirectActivity`: ```xml theme={"system"}

``` `WEB_VIEW` mode needs no manifest work — any scheme is intercepted by the WebView client directly. ### Notes * **Match your URLs.** Whatever your backend passed as `complete_url.href` / `cancel_url.href`, pass the same `Uri` to `startCheckout`. The SDK matches on scheme + host + path; query params on the inbound URL are read by you. * **`order.uuid` lives on your server.** It's not in the `checkout_url` and isn't echoed back — your backend already has it from the session-creation response. ## 9. Testing Use the sandbox environment for testing: ```kotlin theme={"system"} SezzleSDK.configure( publicKey = "sz_pub_your_sandbox_key", environment = SezzleEnvironment.SANDBOX ) ``` Use the [test data](/docs/api/test-cards) to complete test checkouts in sandbox. Switch to `SezzleEnvironment.PRODUCTION` and your live public key before releasing to the Play Store. # Mobile SDKs Source: https://docs.sezzle.com/docs/guides/mobile/introduction Integrate Sezzle directly into your native iOS and Android apps. The Sezzle Mobile SDKs provide two core features: 1. **Promotional Messaging** — drop-in widgets that show installment pricing on product pages 2. **Checkout** — launch a Sezzle checkout session from your app and handle the result Swift Package Manager, CocoaPods. iOS 15+. Maven Central, Gradle. Android 6.0+ (API 23). ## How It Works ```mermaid theme={"system"} sequenceDiagram participant App as Merchant App participant SDK as Sezzle SDK participant API as Sezzle API participant Browser as Browser / WebView App->>SDK: 1. Configure (public key) App->>SDK: 2. Show promotional widget (price) SDK-->>App: Renders installment messaging App->>SDK: 3. Start checkout (order details) SDK->>API: POST /v2/session API-->>SDK: Session + checkout URL SDK->>Browser: 4. Open checkout Browser-->>SDK: 5. Customer completes / cancels SDK-->>App: 6. Callback (order UUID) App->>API: 7. Capture payment (server-side) ``` **Server-driven integration?** If you'd rather keep your public key off-device and have your backend create the Sezzle session directly, the SDK also exposes a pass-URL `startCheckout` overload (`1.2.0`+). Your server creates the session, your app hands the resulting `checkout_url` to the SDK, and the SDK reports back via the same delegate. See the **Server-Driven Integration** section in the [iOS](/docs/guides/mobile/ios#8-server-driven-integration) or [Android](/docs/guides/mobile/android#8-server-driven-integration) guide. ## Checkout Modes The SDK supports two ways to present the Sezzle checkout: | | System Browser | WebView | | ------------------- | --------------------------------------------------------------------------- | ---------------------------------- | | **How it opens** | iOS: `ASWebAuthenticationSession` / Android: Chrome Custom Tab | In-app WKWebView / Android WebView | | **Recommended** | Yes (default) | Opt-in | | **Security** | Runs in a separate browser process | Runs inside your app's process | | **Cookie sharing** | Shares cookies with Safari/Chrome (faster login for returning Sezzle users) | No cookie sharing | | **User experience** | Brief context switch to browser | Stays inside your app | iOS System Browser

## Promotional Messaging The SDK includes a drop-in promotional widget that automatically displays the right installment messaging based on the product price: | Price Range | Message | | --------------------------------------------- | -------------------------------------------------- | | Below minimum (\$35 default) | Widget hidden | | $35 -- $49.99 | "or 4 payments of \$X.XX with Sezzle" | | $50 -- $2,500 | "or 5 payments of \$X.XX with Sezzle" | | Above short-term max (with long-term enabled) | "or monthly payments as low as \$X.XX with Sezzle" | Tapping the widget opens an educational modal showing the full payment schedule: Installment Modal

## Dark Mode Both SDKs automatically adapt to the device's appearance setting. The promotional widget, installment modal, and all brand colors adjust for light and dark mode. Light Mode

## Prerequisites Before you begin, make sure you have: 1. A Sezzle merchant account — sign up here if you don't have one 2. Your Public API Key from the Sezzle Merchant Dashboard 3. A backend server that can call the Sezzle API to capture payments after checkout The SDK uses your **public** API key only. Your private key stays on your server and is used to capture payments after the customer completes checkout. ## Source Code Both SDKs are open source on GitHub: * sezzle/sezzle-merchant-sdk-ios * sezzle/sezzle-merchant-sdk-android # iOS SDK Source: https://docs.sezzle.com/docs/guides/mobile/ios This guide walks you through integrating the Sezzle iOS SDK into your app. By the end, your app will display Sezzle promotional messaging on product pages and launch Sezzle checkout. ### Prerequisites * iOS 15.0+ deployment target * Swift 5.9+ * A Sezzle merchant account with your Public API Key * A backend server to capture payments after checkout A working example app is included in the SDK repo at Example/SezzleCheckoutExample. It demonstrates all widget variants and both checkout modes. ## 1. Installation 1. In Xcode, go to **File > Add Package Dependencies** 2. Enter the repository URL: ``` https://github.com/sezzle/sezzle-merchant-sdk-ios.git ``` 3. Select **Up to Next Major Version** from the latest release 4. Add `SezzleMerchantSDK` to your target Add to your `Podfile`: ```ruby theme={"system"} pod 'SezzleMerchantSDK' ``` Then run: ```bash theme={"system"} pod install ``` **Requirements:** iOS 15.0+, Swift 5.9+ ## 2. Configuration Initialize the SDK once at app startup in your `AppDelegate`: ```swift theme={"system"} import SezzleMerchantSDK @main class AppDelegate: UIResponder, UIApplicationDelegate { func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { SezzleSDK.shared.configure( publicKey: "sz_pub_your_key_here", environment: .production // use .sandbox for testing ) return true } } ``` | Parameter | Type | Default | Description | | ------------- | ------------------- | ------------- | ---------------------------------------------- | | `publicKey` | `String` | Required | Your Sezzle public API key | | `environment` | `SezzleEnvironment` | `.production` | `.sandbox` for testing, `.production` for live | Never include your **private** API key in the app. The SDK only uses the public key. Use your private key server-side to capture payments. ## 3. Promotional Messaging Add a `SezzlePromotionalView` to your product page to display installment pricing: ```swift theme={"system"} import SezzleMerchantSDK let promoView = SezzlePromotionalView( amountInCents: 9999, // $99.99 presentingFrom: self // UIViewController for modal presentation ) view.addSubview(promoView) ``` The widget automatically shows the correct message based on the price and updates when you call: ```swift theme={"system"} promoView.update(amountInCents: 14999) // price changed to $149.99 ``` iOS Widgets

### All Parameters ```swift theme={"system"} SezzlePromotionalView( amountInCents: Int, currency: String = "USD", style: SezzlePromotionalStyle = .light, widgetConfig: SezzleWidgetConfig = .default, presentingFrom viewController: UIViewController ) ``` | Parameter | Type | Default | Description | | ---------------- | ------------------------ | ---------- | ------------------------------------------------ | | `amountInCents` | `Int` | Required | Product price in cents (e.g., 4999 = \$49.99) | | `currency` | `String` | `"USD"` | ISO 4217 currency code (e.g., `"USD"`, `"CAD"`) | | `style` | `SezzlePromotionalStyle` | `.light` | `.light` for light backgrounds, `.dark` for dark | | `widgetConfig` | `SezzleWidgetConfig` | `.default` | Controls pricing thresholds and Pay-in-5 | | `presentingFrom` | `UIViewController` | Required | View controller to present the info modal from | The widget auto-detects dark mode and switches styles via `traitCollectionDidChange`. If you want to force a specific style, pass `.light` or `.dark` explicitly. ### Widget Configuration All config parameters are **optional** — the widget works out of the box with sensible defaults: | Parameter | Default | Description | | -------------------- | ------------------ | ------------------------------------------------------------------------------- | | `minPriceInCents` | `3500` (\$35) | Minimum price to show the widget | | `maxPriceInCents` | `250000` (\$2,500) | Maximum price for short-term (PI4/PI5) | | `enablePayIn5` | `true` | Show "5 payments" for prices at or above the PI5 threshold | | `pi5MinPriceInCents` | `5000` (\$50) | Price threshold for Pay-in-5 | | `longTermConfig` | `nil` (disabled) | Enable long-term monthly payments — set to a `SezzleLongTermConfig` to activate | To customize, pass only the values you want to override: ```swift theme={"system"} let config = SezzleWidgetConfig( longTermConfig: SezzleLongTermConfig( minPriceInCents: 25_000 // $250+ shows monthly payments ) ) let promoView = SezzlePromotionalView( amountInCents: 79900, widgetConfig: config, presentingFrom: self ) ``` ### Custom Promotional Text If you need full control over the UI, use `SezzlePromoDataHandler` to get a styled `NSAttributedString` with the Sezzle logo inline: ```swift theme={"system"} SezzlePromoDataHandler.getMessage(amountInCents: 9999) { attributedString in myLabel.attributedText = attributedString } ``` ## 4. Checkout ### Build the Checkout Object ```swift theme={"system"} let checkout = SezzleCheckout( customer: SezzleCustomer( email: "customer@example.com", firstName: "Jane", lastName: "Doe", phone: "+15551234567", billingAddress: SezzleAddress( street: "123 Main St", city: "Minneapolis", state: "MN", postalCode: "55401", countryCode: "US" ) ), order: SezzleOrder( referenceId: "order-12345", description: "Wireless Earbuds", amount: SezzleAmount(amountInCents: 4599, currency: "USD"), items: [ SezzleItem( name: "Wireless Earbuds", sku: "WE-001", quantity: 1, price: SezzleAmount(amountInCents: 3999, currency: "USD") ) ], taxAmount: SezzleAmount(amountInCents: 350, currency: "USD"), shippingAmount: SezzleAmount(amountInCents: 250, currency: "USD") ) ) ``` #### Customer Fields | Field | Required | Description | | ----------------- | -------- | ----------------------------------- | | `email` | Yes | Customer email address | | `firstName` | No | Customer first name | | `lastName` | No | Customer last name | | `phone` | No | Customer phone number | | `dob` | No | Date of birth (`"YYYY-MM-DD"`) | | `billingAddress` | No | Billing address (`SezzleAddress`) | | `shippingAddress` | No | Shipping address (`SezzleAddress`) | | `tokenize` | No | Tokenize customer for future orders | #### Order Fields | Field | Required | Description | | -------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `referenceId` | Yes | Your internal order/reference ID | | `description` | No | Order description | | `amount` | Yes | Total order amount in cents + currency | | `intent` | No | [`.auth`](/docs/api/core/sessions/postv2session#body-order-intent) (default, capture later from your backend) or `.capture` (auto-capture at checkout completion) | | `items` | No | Line item details | | `discounts` | No | Discount line items (`[SezzleDiscount]`) | | `taxAmount` | No | Tax amount breakdown | | `shippingAmount` | No | Shipping amount breakdown | | `metadata` | No | Custom key-value pairs. The SDK automatically includes `_sdk_platform`, `_sdk_version`, `_device_model`, and `_os_version` — avoid using keys prefixed with `_`. | | `locale` | No | Checkout locale (`.enUS`, `.enCA`, `.frCA`) | | `checkoutFinancingOptions` | No | Restrict to specific plans: `.fourPayBiweekly`, `.fourPayMonthly`, `.sixPayMonthly`. Optional — omit to let Sezzle show all eligible plans. | #### Address Fields (`SezzleAddress`) | Field | Description | | ------------- | ------------------------------- | | `name` | Full name | | `street` | Street address line 1 | | `street2` | Street address line 2 | | `city` | City | | `state` | State or province | | `postalCode` | Postal/ZIP code | | `countryCode` | ISO country code (e.g., `"US"`) | | `phone` | Phone number | ### Start Checkout ```swift theme={"system"} SezzleSDK.shared.startCheckout( checkout, from: self, // presenting UIViewController delegate: self, // SezzleCheckoutDelegate mode: .systemBrowser // or .webView ) ``` ### Handle the Result Conform to `SezzleCheckoutDelegate`: ```swift theme={"system"} extension ProductViewController: SezzleCheckoutDelegate { func checkoutDidComplete(result: SezzleCheckoutResult) { // For this flow, `result.orderUUID` is populated. // (For the server-driven flow, see Section 8.) if let orderUUID = result.orderUUID { // Send orderUUID to your backend to capture payment // POST /v2/order/{orderUUID}/capture print("Order completed: \(orderUUID)") } } func checkoutDidCancel() { // Customer closed checkout without completing print("Checkout cancelled") } func checkoutDidFail(error: SezzleError) { // Handle the error switch error { case .networkError(let underlying): print("Network error: \(underlying)") case .apiError(let statusCode, let message): print("API error \(statusCode): \(message)") case .browserDismissed: print("Browser dismissed") case .notConfigured: print("SDK not configured") case .invalidResponse: print("Invalid response") } } } ``` After `checkoutDidComplete`, send `result.orderUUID` to your backend server. Your server should call `POST /v2/order/{orderUUID}/capture` using your **private** API key to capture the payment. See the [Orders API](/docs/api/core/orders/postv2capturebyorder) for details. ## 5. WebView Mode By default, checkout opens in `ASWebAuthenticationSession` (system browser). To keep the user inside your app, use WebView mode: ```swift theme={"system"} SezzleSDK.shared.startCheckout( checkout, from: self, delegate: self, mode: .webView ) ```

| Mode | Pros | Cons | | ---------------- | ------------------------------------------ | ------------------------------------------ | | `.systemBrowser` | Secure, shares Safari cookies, recommended | Brief context switch | | `.webView` | Stays in-app | No cookie sharing, user logs in every time | ## 6. Dark Mode The SDK automatically adapts to the device's appearance setting. The promotional widget, installment modal, and checkout modal all support dark mode. Light Mode

If you need to force a specific style (e.g., your app doesn't follow the system setting): ```swift theme={"system"} let promoView = SezzlePromotionalView( amountInCents: 9999, style: .dark, // force dark style presentingFrom: self ) ``` ## 7. Error Handling All errors are delivered via `SezzleCheckoutDelegate.checkoutDidFail(error:)`: | Error | When | Suggested Action | | -------------------------------- | --------------------------------------------- | ----------------------------------- | | `.notConfigured` | `SezzleSDK.shared.configure()` was not called | Call `configure()` in `AppDelegate` | | `.networkError` | No internet, timeout, DNS failure | Show retry option | | `.apiError(statusCode, message)` | Sezzle API returned an error | Check status code and message | | `.browserDismissed` | User closed the browser/WebView | Return to product page | | `.invalidResponse` | Unexpected response format | Contact Sezzle support | ## 8. Server-Driven Integration For larger merchants who prefer a fully server-driven integration — no public key on-device, with the backend owning session creation, capture, and refunds — use the alternative `startCheckout` overload introduced in `1.2.0`. ### How it works Your backend creates the checkout session via [`POST /v2/session`](/docs/api/core/sessions/postv2session) with merchant-chosen callback URLs, then hands `order.checkout_url` plus those URLs to the app. The SDK opens the URL, intercepts navigation to your callback URLs, and reports back via `SezzleCheckoutDelegate.checkoutDidComplete(result:)` with the full callback URL — so you can encode your own state in the query string and recover it on completion. ```mermaid theme={"system"} sequenceDiagram participant App as Merchant App participant Backend as Merchant Backend participant SDK as Sezzle SDK participant API as Sezzle API App->>Backend: 1. Request checkout Backend->>API: 2. POST /v2/session (with merchant callback URLs) API-->>Backend: order.uuid + order.checkout_url Backend-->>App: 3. checkout_url + callback URLs App->>SDK: 4. startCheckout(checkoutURL:completeURL:cancelURL:…) SDK-->>App: 5. checkoutDidComplete(result.callbackURL) App->>Backend: 6. Map callback URL state → orderUUID Backend->>API: 7. Capture payment ``` ### Step 1 — Backend creates the session Pick any callback URLs you want — a custom scheme like `yourapp-sezzle://...` or HTTPS deep links. You can encode state in the query string (e.g. `yourapp-sezzle://done?orderRef=12345`) and recover it from the SDK callback. Persist `order.uuid` server-side; the app only needs `order.checkout_url` plus the two callback URLs. **Don't put PII, auth tokens, or anything sensitive in the callback URL query string.** The callback URL is rendered in the browser and may be logged. Use opaque references (a random `orderRef` mapped server-side) — never the customer's email, phone, payment data, or session tokens. Custom URL schemes are also **not exclusive** — another app installed on the device can register the same scheme and intercept the callback. For maximum security in production, use **Universal Links** (verified HTTPS deep links) with `.webView` mode — they're tied to a domain you control, so other apps can't claim them. ### Step 2 — App presents checkout ```swift theme={"system"} SezzleSDK.shared.startCheckout( checkoutURL: URL(string: checkoutURL)!, // from order.checkout_url (String → URL) completeURL: URL(string: "yourapp-sezzle://checkout/done")!, // matches your server's complete_url.href cancelURL: URL(string: "yourapp-sezzle://checkout/cancelled")!, // matches your server's cancel_url.href from: self, delegate: self, mode: .webView // or .systemBrowser ) ``` `SezzleSDK.shared.configure(publicKey:)` is **not** required for this flow — there's nothing for the SDK to authenticate. ### Step 3 — Read the result ```swift theme={"system"} func checkoutDidComplete(result: SezzleCheckoutResult) { guard let callbackURL = result.callbackURL else { return } let orderRef = URLComponents(url: callbackURL, resolvingAgainstBaseURL: false)? .queryItems? .first(where: { $0.name == "orderRef" })? .value // Look up orderRef in your backend, then call /v2/order/{order.uuid}/capture } ``` ### Notes * **`ASWebAuthenticationSession` requires a custom URL scheme** for the callback (`callbackURLScheme:` parameter). HTTPS callbacks aren't accepted by the auth session API. For HTTPS-based deep links (e.g. backed by Universal Links), use `.webView` mode — it intercepts navigation directly via `WKNavigationDelegate` and works with any scheme. * **Match your URLs.** Whatever your backend passed as `complete_url.href` / `cancel_url.href`, pass the same URLs to `startCheckout`. The SDK matches on scheme + host + path; query params on the inbound URL are read by you. * **`order.uuid` lives on your server.** It's not in the `checkout_url` and isn't echoed back — your backend already has it from the session-creation response. ## 9. Testing Use the sandbox environment for testing: ```swift theme={"system"} SezzleSDK.shared.configure( publicKey: "sz_pub_your_sandbox_key", environment: .sandbox ) ``` Use the [test data](/docs/api/test-cards) to complete test checkouts in sandbox. Switch to `.production` and your live public key before releasing to the App Store. # Introduction Source: https://docs.sezzle.com/docs/guides/sezzle/introduction Sezzle provides an effortless way to integrate flexible payment options into your checkout process. With a design focused on quick and efficient setup, our solution allows you to get started faster than you might anticipate. ## Get Started with Sezzle Select the integration option that works best for your store. Utilize our APIs to integrate Sezzle into your custom online store. Integrations for Shopify, Magento 2, Wix, WooCommerce, and more. * Accept Sezzle payments as credit card transactions. Empower your customers to pay with Sezzle at your physical store location. ## Conversion Boosters Increase sales with these additional Sezzle products. Showcase Sezzle as a payment method on product pages. Increase conversion rates and enhance customer satisfaction. ## Additional Resources These will speed up your Sezzle integration. Accept web and in-app payments through our expansive API integration. Contact our Merchant Support team to get help with integrating Sezzle. ## How Sezzle Works The shopper adds your product to their cart. The shopper selects "Buy Now, Pay Later with Sezzle" at checkout. The shopper selects their preferred installment plan. The shopper completes their Sezzle order. ## Popular Integrations Screenshot2025 05 12at10 46 33AM Pn

# Using Virtual Card SDK Source: https://docs.sezzle.com/docs/guides/virtual/automated 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. # Introduction Source: https://docs.sezzle.com/docs/guides/virtual/introduction * Sezzle Virtual Card allows merchants to: * Accept Sezzle payments as credit card transactions. * Seamlessly integrate with existing credit card forms at checkout. * The virtual card is issued by Sezzle and charged through **your existing payment processor** (e.g., Stripe, Cybersource, Braintree). Your systems will handle the card data to process the charge. * For API-related questions, contact the Sezzle team via the [Merchant Help Request](https://merchant-help.sezzle.com/hc/en-us/requests/new) form. * An approved Sezzle account is required to begin integration; [sign up](https://dashboard.sezzle.com/merchant/signup) if you don’t have one. * Endpoints in this guide require an [authentication](/docs/api/core/authentication/postauthentication) token. You can test your integration with Sezzle using [Sezzle sandbox test environment](/docs/api/environments). This product is currently only available in the United States. Support for Canada coming soon. ## Integration Options | | [Virtual Card SDK](./automated) | [Manual Integration](./manual) | | ------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | **Best for** | Most merchants -- fastest setup | Merchants needing full control | | **How it works** | Drop-in SDK handles checkout popup/iframe and card data delivery | You implement the `postMessage` listener and card session API calls | | **Tokenization support** | Yes -- use `card_response_format: "token"` to receive a token instead of raw card data | Not available -- card data is always delivered to your frontend | **PCI DSS consideration:** Because you will receive and process virtual card data through your payment gateway, ensure your integration aligns with your current PCI compliance level. The SDK’s [tokenization option](./automated#oncomplete-with-tokenization) keeps card data out of the browser, which can reduce your PCI scope. The shopper selects "Make a purchase request" on the Virtual Card tab. The shopper enters the amount they plan to spend. The shopper reads the loan terms and continues if they agree. The shopper uses the Virtual card at your checkout or terminal. # Manual Integration Source: https://docs.sezzle.com/docs/guides/virtual/manual If the [Virtual Card SDK](./automated) is not a viable option, the manual integration will guide you through the steps to complete a virtual card session in your checkout. The manual integration delivers the **full card number (PAN) and CVV** directly to your frontend JavaScript via `postMessage`. This places your frontend in PCI DSS scope. If you want to minimize PCI exposure, consider the [Virtual Card SDK](./automated) with the [`card_response_format: "token"` option](./automated#oncomplete-with-tokenization), which keeps card data out of the browser. ## Overview 1. Create a [virtual card session](/docs/api/core/sessions/virtual/postv2sessioncard) 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 the message `event.origin` matches the expected Sezzle domain 6. Verify message `event.data` exists 7. Verify `event.data.szl_source` `=` `v_card` 8. Verify `event.data.card` and `event.data.holder` both exist * If they exist * Use card and holder data to submit the order by credit card * If they don't exist * The user did not provide virtual card data ## Example Javascript ```javascript [expandable] theme={"system"} var SEZZLE_ORIGIN = "https://dashboard.sezzle.com"; window.addEventListener("message", function (event) { // Validate the message origin for security if (event.origin !== SEZZLE_ORIGIN) { return; } var data = event.data || Object.create(null); if (data.szl_source !== "v_card") { return; } var card = data.card; var holder = data.holder; if (!card && !holder) { console.log("failed virtual card session"); return; } // Submit card and holder data to your payment processor. // IMPORTANT: Do not log or store raw card data (PAN, CVV) // in your frontend. Send it directly to your server or // payment gateway for processing. submitToPaymentGateway({ card: { number: card.pan, cvv: card.cvv, expiryMonth: card.expiryMonth, expiryYear: card.expiryYear, firstName: card.firstName, lastName: card.lastName, }, billingAddress: { email: holder.email, phone: holder.phone, firstName: holder.firstName, lastName: holder.lastName, address1: holder.address1, address2: holder.address2, city: holder.city, state: holder.state, country: holder.country, postalCode: holder.postalCode, }, }); }); ``` # Checkout Installments Widget Source: https://docs.sezzle.com/docs/guides/widgets/checkout-installments ## Purpose The checkout installments widget shows a sample installment plan, including installment amounts and due dates, at the point of final decision. Checkout Installment Widget Pn

## Installation Select the implementation that fits your needs: * [NPM Package](#npm-implementation) * [Code Snippet (auto-updates)](#cdn-implementation) * [Code Snippet (static file)](#static-implementation) ### NPM Implementation Using npm: `npm install @sezzle/sezzle-installment-widget@latest` Within your checkout page, add the following code snippet to import the library: ```html theme={"system"} import SezzleInstallmentWidget from @sezzle/sezzle-installment-widget ``` Where you want the widget to render, add the snippet from the [Configuration](#configuration) section below, updating options to determine the price. ### CDN Implementation Within your checkout page, add the following code snippet to import the library: ```html theme={"system"} ``` 7. Back in the Javascript file, update the values of the following options as applicable, then click Save: * merchantLocale (optional): The country code. Currently Sezzle is only available in the United States and its territories, and Canada. Defaults to "US". * currencySymbol (optional): The currency symbol to display in the installment widget. If unassigned, the currency symbol will be automatically detected in the targeted checkout total element contents or default to \$ * checkoutTotal (required): The element where the checkout total is rendered. (Example value is given for Shopify default) #### Platform-Agnostic Method 1. Create a copy of the code from [Github](https://github.com/sezzle/static-widgets/blob/production/src/sezzle-checkout-installment-widget/sezzle-checkout-installment-widget.js) within your store's theme code, then import it into the checkout page code. 2. Invocation: * Option 1 (recommended): To inject the placeholder element dynamically, add the following lines of code to run once the rest of the page has loaded, updating `sezzlePaymentLine` to target the Sezzle payment method line, below which the installment widget asset will display: ```html theme={"system"} ``` * Option 2: Enter the following two lines of code where the installment widget should appear: ```html theme={"system"} ``` 3. Back in the Javascript file, update the values of the following options as applicable, then Save changes: * merchantLocale (optional): The country code. Currently Sezzle is only available in the United States and its territories, and Canada. Defaults to "US". * currencySymbol (optional): The currency symbol to display in the installment widget. If unassigned, the currency symbol will be automatically detected in the targeted checkout total element contents or default to \$ * checkoutTotal (required): The element where the checkout total is rendered. (Example value is given for Shopify default, other top platform values saved as comments) ### Configuration Not applicable for static implementation ```html theme={"system"} ``` ```html theme={"system"} ``` Either `platform` or `checkoutTotalElemTargetPath` is required, but not both. The ecommerce platform which hosts the checkout page. If not supported, please refer to checkoutTotalElemTargetPath. Available options: `shopify`, `woocommerce`, `3dcart`, `commentsold`, `magento2`, `prestashop`, `shopware`, `opencart` The ID or class name of the element containing the total order amount. The currency symbol to show in the price. By default, the widget will mimic the currency from the total order amount targeted element if present and fallback to \$ if not provided. # On-Site Messaging Widget Source: https://docs.sezzle.com/docs/guides/widgets/sdk ## Purpose Boost conversions and increase average order value by showcasing Sezzle’s financing options to shoppers as they browse your site. ## Overview The Sezzle on-site messaging widget displays available financing options on product and cart pages, encouraging purchases. Follow the installation instructions below to add the widget to your website. Attachment(1) Pn

## Installation * **One-Click Installation**: Many leading platforms offer one-click installation with Sezzle. [Check for compatibility with your platform](https://docs.sezzle.com/docs/plugins/). * **Manual Installation**: If one-click installation is unavailable or incompatible with your theme, refer to the manual installation guide or contact [merchantsupport@sezzle.com](mailto:merchantsupport@sezzle.com) for assistance. ### On-Site Messaging Widget Script (required) The following imports the Javascript file required to render the on-site messaging widget, along with any saved account settings. Place this script at the bottom of the code file for the HTML page where the widget is to render. ```html theme={"system"} ``` Replace `{merchant_id}` with your 36-character value from your [Merchant Dashboard](https://dashboard.sezzle.com/merchant/settings/business). A pre-populated snippet should be provided in your Sezzle Merchant Dashboard Setup Checklist. ### Customization Sezzle provides extensive configuration options to tailor the on-site messaging widget to your site’s needs. Our engineering team is available to ensure seamless integration with your website’s design and functionality. Contact [merchantsupport@sezzle.com](mailto:merchantsupport@sezzle.com) for assistance, or follow the next section to configure the widget yourself. #### Merchant Configuration Merchants may opt to manage their configuration internally. If your local configuration is being overridden by a different value, please contact Sezzle Merchant Support to remove the saved override. The below configuration script must appear in the code *before* the widget script in the previous section. ## `document.sezzleConfig` Options ```html expandable theme={"system"} ``` ```html expandable theme={"system"} ``` Allows multiple configurations for one store to suit different page types, layouts, or applications. View all available options for customization. ID, class, or path to the element in the webpage where the product price text value will be detected.\ To indicate a path, subpaths are separated by '/', IDs are preceded by '#', classes by '.', and tag names are suffixed with index (`tagName-Index`). Indexes are zero-based. e.g. '#ProductSection/.product-price/SPAN-1' would target the 2nd 'SPAN' element contained within elements that contain the 'product-price' class which are contained within the element with an ID of 'ProductSection'. Path from `targetXPath` to the element after which the Sezzle widget should be rendered.\ Use '.' for sibling placement, '../' to move up to parents, and tag-index selectors to move down. Same syntax as `targetXPath`. e.g. '../../BUTTON-0' would go to the grandparent element of the targetXPath and place the widget after the first button found within that container. Specific word appearing in the URL of pages where the widget config should apply. Typical values are 'product' or 'cart'. Updates the logo color to coordinate with different background colors. If not specified, the widget will attempt to detect the background color and apply a contrasting logo. Available options: `dark`, `light`, `black-flat`, `white-flat`. Custom styling to apply to the Sezzle widget container. Accepts CSS in JSON format. Keys must use camelCase, be wrapped in quotes, and separated by commas. Key should be the CSS property you wish to set, in camelCase, value should be type string Custom styling to apply to the Sezzle text within the widget. Accepts CSS in JSON format. Keys must use camelCase, be wrapped in quotes, and separated by commas. Key should be the CSS property you wish to set, in camelCase, value should be type string Custom styling to apply to the Sezzle logo within the widget. Accepts CSS in JSON format. Keys must use camelCase, be wrapped in quotes, and separated by commas. Key should be the CSS property you wish to set, in camelCase, value should be type string The path from the targetXPath to the observable element Function receives two parameters. The first is the related element per `relatedPath`, the second is the widget that corresponds to this `targetXPath` element. Write a custom function to check condition on relatedPath, then perform an action on widget. Direct child elements of `targetXPath` to be disregarded when detecting the price. Useful for handling variations between sale and regular-priced items. Text strings within `targetXPath` to be disregarded when detecting the price and rendering the widget. XPath of elements that should be hidden when Sezzle's widget is showing.\ Despite the name, this config accepts an array of XPaths. e.g. \["#viabill-pricetag",".afterpay-paragraph","QUADPAYWIDGET-0"] Alignment of the widget relative to the parent element. Available options: `left`, `center`, `right`, `auto` Screen width in pixels below which the alignment switches to `alignmentSwitchType`. Common breakpoint: 768px (for handheld vs desktop). Alignment of the widget to apply when viewport width is narrower than `alignmentSwitchMinWidth`. Available options: `left`, `center`, `right`, `auto` Afterpay's logo is appended to widget content. When clicked, the competitor's modal will display. Klarna's logo is appended to widget content. When clicked, the competitor's modal will display. Minimum price in cents for which Sezzle can be selected at checkout. If the price at `targetXPath` is lower than this number, the widget will render with a note stating the minimum eligible price required. This configuration does not prevent a customer from checking out with Sezzle below this price. For more information on setting a gateway minimum, contact your Merchant Success representative or use the Contact Us section of the Sezzle Merchant Dashboard. Maximum price in cents for which the widget should be rendered. If the price at `targetXPath` is higher than this number, the widget will not render on the page. Language in which the widget text should be rendered. If the specified language is not supported, the translation will default to English. Available options: `left`, `center`, `right`, `auto` Can attach event listeners to DOM elements and re-initialize the widget. The id or class of the element to observe The event type for which to observe, upon which to re-render the widget #### Simple Example ```html theme={"system"} ``` ```html theme={"system"} ``` ## FAQs The widget SDK is fast and lightweight, and has not been shown to directly impact site performance. Additionally, it is designed to load last so it does not interrupt the user experience. If site performance is already slow, this may cause the widget to appear "late". Perform a [site performance test](https://pagespeed.web.dev/) before and after installation to confirm, being sure to review the itemized report, not just the overall score. There is no cost associated with the widget itself. In fact, having widgets are a prerequisite to some of our merchant perks. # Static On-Site Messaging Widget Source: https://docs.sezzle.com/docs/guides/widgets/static The Static On-Site Messaging Widget enables merchants to integrate the Sezzle promotional widget into their website without direct communication with Sezzle’s servers. All widget code, custom configurations, images, and stylesheets are hosted locally within the merchant’s store theme. This approach offers: * Faster Load Times * Local hosting reduces dependency on external servers. * Greater Control * Merchants have full authority over the widget’s appearance and behavior, as the Sezzle team cannot modify it. This local control means merchants are responsible for any updates or changes to the widget. ## Installation Select the implementation that fits your needs: * [NPM Package](#npm-implementation) * [Code Snippet (Platform Agnostic)](#html-implementation) * [Code Snippet (Shopify)](#shopify-implementation) ### NPM Implementation If your website is built with React, please refer to the package and documentation [here](https://www.npmjs.com/package/@sezzle/sezzle-react-widget). Using npm: `npm install @sezzle/sezzle-static-widget@latest` Within your product page, add the following code snippet where you want the widget to render, updating the path to node\_modules for your file structure: ```html theme={"system"} ``` Use the Configuration options below to customize the on-site messaging widget appearance as desired. ### HTML Implementation Implementation varies greatly by platform, theme, etc. Below is a general overview of the process. The code snippets below are samples and may need to be modified to fit your site. For Shopify merchants, please proceed to the next section. 1. Create a new Javascript file within your site's code where appropriate 2. Copy and paste [this minified code](https://github.com/sezzle/static-widgets/blob/production/dist/bundle.js) into the newly created file 3. Import the new file into the page(s) where the Sezzle widget will be added ```html theme={"system"} ``` 4. Create a placeholder element where the Sezzle widget should be rendered on the page(s), usually below the price container element ```html theme={"system"} ``` 5. Add the following script below the placeholder element, updating the amount value to reflect your price variable which renders the current product price or cart total as applicable ```html theme={"system"} ``` 6. Preview your changes to confirm the widget is displaying correctly in each of the following scenarios * Use the Configuration options below to customize the widget appearance as desired: * Regular Price * Sale Price * Variant Selection * Desktop * Mobile ### Shopify Implementation 1. Log into your Shopify store admin 2. Click `Online Store` > `Themes` 3. Next to the theme you wish to edit, click `Actions`, then select `Edit Code` 4. Under the `Assets` folder, click `Add a new asset` 5. On the `Create a Blank File` tab, name the file `sezzle-static-widget` and select `.js` as the file type, then click `Add Asset` 6. Copy the code from the [repository file](https://github.com/sezzle/static-widgets/blob/production/dist/bundle.js) and paste it into this new file, then click `Save` 7. Add the following lines of code wherever the widget should render on the product page within `templates/product.liquid` or `sections/product-template.liquid` as applicable ```html theme={"system"} {{ 'sezzle-static-widget.js' | asset_url | script_tag }} ``` 8. Add the following lines of code wherever the widget should render on the cart page within `templates/cart.liquid` or `sections/cart-template.liquid` as applicable ```html theme={"system"} {{ 'sezzle-static-widget.js' | asset_url | script_tag }} ``` ## Customizing the Configuration Once the on-site messaging widget is rendering, additional configurations can be added to the AwesomeSezzle to change the appearance. Below is an example featuring all the options. However, amount is the only required value. ```html expandable theme={"system"} ``` ```html theme={"system"} ``` The target price amount, in dollar format.\ Provide the product price variable as a template-literal.\ Shopify Liquid Example: `'{{ product.selected_or_first_available_variant.price | money }}'` Provide the ID name or array of ID names that correspond to the widget placeholder elements where the widget should be rendered. Number of installments by which the shopper will pay the total, calculates installment amount. Pay-in-4 and Pay-in-5 are both available at checkout. Pay-in-5 modal reflects both plans, whereas Pay-in-4 modal will only reflect 4 installments. Available options: 4, 5 Updates the logo color to coordinate and contrast with different background colors of websites. If `theme` is not specified, the widget will attempt to detect the background color and apply the appropriate contrasting logo. Use "light" or "black-flat" for light backgrounds, and "dark" or "white-flat" for dark backgrounds. Available options: `dark`, `light`, `black-flat`, `white-flat` Maximum width of the widget element in pixels. Set to 200 to render the widget nicely on 2 lines, or 120 for 3 lines. Amount of space above the widget in pixels. Amount of space below the widget in pixels. Amount of space left of the widget in pixels. Amount of space right of the widget in pixels. Alignment of the widget relative to the parent element. Available options: `left`,`center`, `right`, `auto`. Screen width in pixels below which the alignment switches to `alignmentSwitchType` instead of `alignment`. The most common breakpoint is *768* (handheld vs desktop). `alignmentSwitchMinWidth` is typically only necessary when alignment is not set to `auto`. Alignment of the widget relative to the parent element to be applied when the viewport width is narrower than `alignmentSwitchMinWidth`. Available options: `left`,`center`, `right`, `auto`. Color of the widget text. Accepts all CSS color formats: hex, rgb(), hsl(), etc. Font family of the widget text. Font size of the widget text in pixels. Enter numbers only — do not include units like `px`! Boldness of the widget text. 100 is the lightest, 900 is the boldest. Specifies the page category on which the widget is being rendered. Avaialble options: `product-page`, `product-preview`, `cart`. Sets the CSS value of fixed-height. Ratio at which to scale the Sezzle logo. The space the logo occupies between the widget text and the More Info link/icon is determined by the font size. Custom styling to apply to the Sezzle logo within the widget. The object accepts any CSS styling in JSON format. Keys must be camelCase. Language in which the widget text should be rendered. If the specified language is not supported, the translation will default to English. Available options: `en`, `fr`, `es`, `de`. Allows widget installment price to calculate and format correctly for foreign currencies. Available options: `default`, `comma`. Allows widget to render the correct program details, depending on if the merchant is enrolled through Sezzle North America or Sezzle Europe. Available options: `North America`, `Europe`. ## Methods The following functions are built into the static on-site messaging widget and are ready for use for your on-site messaging widget installation. Simply add the applicable snippet to your webpage code, updating the event listener and variables as necessary. ### `alterPrice(newPrice)` Alters price on widget. Create an event listener after `renderSezzle.init()` that invokes this function where `newPrice` is the new price value of the selected variant. Example: ```javascript theme={"system"} document.onchange = function () { var newPrice = "${yourPriceVariableHere}"; renderSezzle.alterPrice(newPrice); }; ``` ### `renderModalByfunction()` Opens the Sezzle modal by a function. Create an event listener that invokes this function if the event location is other than the info icon. ```javascript theme={"system"} var clickElement = document.querySelector("#yourClickableElementIdHere"); clickElement.addEventListener("click", function () { renderSezzle.renderModalByfunction(); }); ``` ### `isMobileBrowser()` Returns true on mobile browser. Use this event to show or hide the widget in different page locations based on device type. ```javascript theme={"system"} document.onreadystatechange = function () { if (renderSezzle.isMobileBrowser()) { document.getElementById("sezzle-widget-mobile").style.display = "block"; document.getElementById("sezzle-widget").style.display = "none"; } else { document.getElementById("sezzle-widget").style.display = "block"; document.getElementById("sezzle-widget-mobile").style.display = "none"; } }; ``` ### `getElementToRender()` Returns Element where the widget will be rendered. Create an event listener that invokes this function if the widget should appear when the event occurs. ```javascript theme={"system"} document.body.insertBefore( renderSezzle.getElementToRender(), document.getElementById("price").nextElementSibling ); ``` # Before You Begin Source: https://docs.sezzle.com/docs/plugins/before-you-begin 1. You should have a Sezzle merchant account * Please visit our [signup page](https://dashboard.sezzle.com/merchant/signup) if you don't have an account 2. Make sure you know the following Sezzle details for your account * [Merchant ID](https://dashboard.sezzle.com/merchant/settings/business) * [Public API Key](https://dashboard.sezzle.com/merchant/settings/apikeys) * [Private API Key](https://dashboard.sezzle.com/merchant/settings/apikeys) 3. Familiarize yourself with the [transaction flow](https://docs.sezzle.com/docs/guides/direct/introduction) when buying with Sezzle # BigCommerce Source: https://docs.sezzle.com/docs/plugins/big-commerce This guide explains how to add Sezzle as a payment option on your BigCommerce website, enabling customers to use Sezzle at checkout. This integration is only available with [BigCommerce's Optimized One Page Checkout](https://support.bigcommerce.com/s/article/Optimized-Single-Page-Checkout?language=en_US).