---
updatedAt: 2026-08-30T23:14:55.000Z
agentTools:
  projectIndex: https://docs.web2wave.com/llms.txt
---

# Zotlo integration

Connect Zotlo Web SDK checkout, map subscription packages to web2wave prices, and wire up webhooks.

# Why Zotlo

<Anchor label="Zotlo" target="_blank" href="https://zotlo.com/">Zotlo</Anchor> is a subscription commerce platform with an **embedded Web Checkout SDK** - buyers pay on your paywall without leaving the funnel. web2wave mounts the Zotlo form inline, tracks subscriptions from Zotlo webhooks, and supports sandbox testing before going live.

***

# Before you start

* Create a <Anchor label="Zotlo merchant account" target="_blank" href="https://console.zotlo.com/pub/auth/register">Zotlo merchant account</Anchor> and complete onboarding (*<Anchor label="Merchant Application" target="_blank" href="https://console.zotlo.com/account/merchant-application">Merchant Application</Anchor>*) in the Zotlo dashboard.
* <Anchor label="Create your Project" target="_blank" href="https://console.zotlo.com/projects">Create your Project</Anchor> and you will be ready for further configuration.

<Image align="center" border={true} caption="Creating your Project in Zotlo" src="https://files.readme.io/bc69bd77a616da223e4a7769c6b58c67209d46fbb61e3aec56e09781900c2849-image.png" />

* Reference: [Zotlo docs](https://docs.zotlo.com/).

<Image align="center" border={true} caption="Four Steps required to set up in Zotlo dashboard" src="https://files.readme.io/6c88703bf7b9c46c1b43a5bc4561b96ebf7acb6ea216c22da3ea7d44ac3790c6-image.png" />

***

# Integration guide

## Part 1 – Get credentials in Zotlo

**1:** In Zotlo open **Integrations → Developer Tools → Checkout SDK** and copy the **Checkout SDK keys** (separate for Live and Sandbox).

<Image align="center" border={true} caption="Checkout SDK keys" src="https://files.readme.io/c560ebd485fd04d89d1399c732cfca85ba1f2d2d347f75414c3b388c54d2804e-image.png" />

**2:** In **Integrations → Developer Tools → API Keys** copy:

* **Access Key**
* **Access Secret**
* **App ID**

<Image align="center" border={true} caption="API Keys" src="https://files.readme.io/563a714c9242c6636cb31d9d723a0c4ed4674467d7401f90a6b1098664ea9cad-image.png" />

**3:** In **Integrations → Developer Tools → Webhooks** paste the webhook URLs from web2wave (Part 3) into **all four categories**:

* Payments
* Failed Payments
* Subscription Status
* Refunds

Use the **Live Mode URL** for production and the **Sandbox Mode URL** for sandbox. The same endpoint handles every event type — web2wave routes by `queue.type` / `queue.eventType`.

> **Note:** Zotlo does not sign webhooks. web2wave accepts deliveries only when they carry `web2wave_user_id` (and optionally `web2wave_project_id`) from the checkout — i.e. payments that started on your paywall.

***

## Part 2 – Create packages in Zotlo

**4:** In Zotlo open **Catalog→ Sales Packages** and create a package for each plan you sell (billing period, price, currency, trial if any).

<Image align="center" border={true} caption="Creating a package in Zotlo dashboard" src="https://files.readme.io/de90ff39ed78093525e9d120f6e89c9a13cab0c831b1c8e1481e6914f54c2367-image.png" />

**5:** After Zotlo is connected (Part 3), import those packages into web2wave (Part 4). You can also copy each package's **`packageId`** and paste it as the price **External code** if you create a price by hand.

***

## Part 3 – Connect Zotlo to web2wave

**6:** In web2wave open **Projects → \[your project] → Payments** and enable **Zotlo**.

<Image align="center" border={true} caption="Keys to be entered from Zotlo dashboard" src="https://files.readme.io/54ea1b5d7d7d0ffeb34fa8bf4bc90d2f77b7276387daafa5026ab0f0a52532f1-image.png" />

**7:** Fill in the credentials from Part 1:

| Field         | Where in Zotlo                 |
| ------------- | ------------------------------ |
| Web SDK Token | Developer Tools → Checkout SDK |
| Access Key    | Developer Tools → API Keys     |
| Access Secret | Developer Tools → API Keys     |
| App ID        | Developer Tools → API Keys     |

<Image align="center" border={true} caption="Adding Web SDK Token (Live Mode Key) by copying it from Zotlo, Developer Tools → Checkout SDK" src="https://files.readme.io/a181328570df83b637fb3602b1509ac35dd370f373bf17b74760885d68913ac6-image.png" />

<Image align="center" border={true} caption="Adding API Keys in web2wave by copying it from Zotlo" src="https://files.readme.io/c4b83ccfca9cad5d4f77c50025de0129156a63ed772891f8bf19b820e2736f77-image.png" />

Fill both **Production Keys** and **Sandbox Keys** columns if you test in sandbox.

**8:** Copy the webhook URLs shown in project settings:

* **Live:** `https://<your-project>.web2wave.com/zotlo/webhook?livemode=1`
* **Sandbox:** `https://<your-project>.web2wave.com/zotlo/webhook?livemode=0`

<Image align="center" border={true} caption="**Projects → [your project] → Payments** Zotlo, Webhooks section" src="https://files.readme.io/0b2254ddeeb2eb465c21dd3049989f5c321837ccf532bcd160b113c4c5cf5b5a-image.png" />

Paste each URL into the matching **Live Mode URL** / **Sandbox Mode URL** fields in all four Zotlo webhook categories (Part 1, Step 3).

<Image align="center" border={true} caption="Add the same webhook URLs Live for Live, Sandbox for Sandbox from web2wave, save it and &#x22;Send Test Webhook&#x22; button will appear" src="https://files.readme.io/1cbfa3ac10e62bba3e1309b4e7ba497c7bb60927076517b5c1ad68ecb29c5037-image.png" />

**9:** Click **Save**, then use **Send Test Webhook** in Zotlo to confirm connectivity.

<Image align="center" border={true} caption="Sending a test webhook from Zotlo dashboard" src="https://files.readme.io/7ff9f23906701e8eaffc7317f78637a593d15e2d60e6f69a1e95ff64c8bbc043-image.png" />

Expected result:

<Image align="center" border={true} src="https://files.readme.io/195578126379ed1ba150a26d1d034e4967405482901f3665cc05eaf8edbfe499-image.png" className="border" />

*If upon checking you will not see a **Success** message, please contact web2wave support team.*

***

## Part 4 – Map prices and configure the paywall

**10:** In web2wave go to **Plans and Prices → Import Plans and Prices**. Select your project, set **Payment System** to **Zotlo**, and click **Start Import**.

To create a price by hand instead, use **Create new price**:

<Image align="center" border={true} caption="Creating new price in web2wave" src="https://files.readme.io/fee8c6d1afc331ab8da7774c5cdf6124cd9f14217719e13528518246ef4fbcf0-image.png" />

For each price that should bill through Zotlo:

* Set **Payment system** context via the plan (live prices → production keys, sandbox prices → sandbox keys).
* Set **External code** to the Zotlo **`packageId`** from Part 2.

<Image align="center" border={true} caption="Creating a Live price in web2wave dashboard for Zotlo payment system" src="https://files.readme.io/a555600dcb83746640f2f90405f7d80ba0c03e68695f86aa109b889ac3c8cfa6-image.png" />

**11:** Open the paywall editor:

* Set **Main payment system** to **Zotlo**.
* Add your Zotlo-linked prices to the paywall.

<Image align="center" border={true} caption="Selecting created prices in a paywall, Settings tab" src="https://files.readme.io/fb7580c147ddc89d82d7f222eab526a756d6ea8078ad54a5711331959a8870f6-image.png" />

* Add the **Zotlo form** block where the embedded checkout should appear.

The paywall must collect the buyer's **email before** the Zotlo form renders - web2wave passes it to Zotlo as `subscriberId` so returning customers can reuse saved cards.

***

## Part 5 – Test purchase

**12:** Run a sandbox purchase and verify:

* The Zotlo checkout renders inline and reloads when the buyer switches prices.
* Webhooks appear under **Project → Webhooks**.
* A new subscription shows in the cabinet with the Zotlo transaction / subscription id.

***

# Troubleshooting

**Q:** Checkout shows *"Zotlo is not configured for this paywall."*

* **Resolution:** Add the Web SDK Token for the environment that matches the selected price (`livemode`).

**Q:** Checkout shows *"Could not open Zotlo checkout"* or the form stays empty.

* **Resolution:** Check that the price **External code** is set to a valid Zotlo `packageId` and that currency / amount / period match the Zotlo package.

**Q:** Payment succeeds in Zotlo but no subscription appears in web2wave.

* **Resolution:** Confirm webhooks are configured in all four Zotlo categories and point to the correct Live/Sandbox URL. Check **Project → Webhooks** for failed deliveries. Zotlo retries failed webhooks (10 min, 30 min × 3, 1 h) and drops the event after the 5th attempt.

**Q:** Need to refresh revenue for a subscription?

* Open the subscription in the cabinet and click **Recalculate**. web2wave pulls the latest transaction history from Zotlo via the API.

<br />