Use this file to discover all available pages before exploring further.
You sell a course or digital product on an external gateway (Hotmart, Kiwify, Eduzz, Stripe Checkout) and want the purchase to automatically unlock access to a group, course or space inside your Cativa community. This guide walks through the recommended architecture, what’s available today and what’s coming soon.
A customer buys “Premium Course” on Hotmart. Within seconds they get access to the “Premium Students” group and to the course inside your Cativa community.The bridge between both sides is the badge-as-permission concept: the Premium badge is configured in the Console as the access requirement on that group and course. Once the user gets the badge, access shows up automatically. When the badge is removed, access is gone.
Cativa API Key — generated in the Console (Developers > API Keys). See Quick Start: API Key.
Badge configured in the Console — create the Premium badge (or whatever your product is called) and configure it as the access requirement on the group/course. See Badges as Permissions.
Purchase webhook from your gateway — Hotmart, Kiwify, Eduzz and Stripe fire a webhook to your server’s endpoint when a purchase is confirmed. Do not point the gateway webhook directly at Cativa — you need a proxy server that receives, validates and translates the event.
A reliable buyer email — every gateway sends the email in the purchase payload. That’s the join key with the Cativa user.
Each gateway has its own webhook format and its own signing mechanism. Configure the webhook in the gateway dashboard pointing to an endpoint on your server (e.g. https://myapp.com/webhooks/hotmart).Cativa does not document the gateway webhook formats — refer to the official docs:
import express from 'express';const app = express();app.post( '/webhooks/hotmart', express.json(), async (req, res) => { // 1. Verify the gateway signature here (per gateway docs) const event = req.body; // Hotmart uses event types like "PURCHASE_APPROVED", "PURCHASE_CANCELED", etc. if (event.event === 'PURCHASE_APPROVED') { await handlePurchase({ email: event.data.buyer.email, productId: event.data.product.id, purchaseId: event.data.purchase.transaction }); } if (event.event === 'PURCHASE_CANCELED' || event.event === 'PURCHASE_REFUNDED' || event.event === 'PURCHASE_CHARGEBACK') { await handleCancellation({ email: event.data.buyer.email, productId: event.data.product.id, purchaseId: event.data.purchase.transaction }); } // Reply 2xx fast — process the rest in the background if you can. res.status(200).send('ok'); });
Always verify the gateway webhook signature before trusting the data. Without it, anyone who finds your URL could grant arbitrary badges.
2
Identify the user on Cativa by email
Two situations today:Case A — the buyer already has a Cativa account: you need to find their User.Id.
The public endpoint for partners to look up an arbitrary user by email is coming soon. Today, that lookup uses an admin endpoint that’s not available to partner API Keys.Recommended workaround: keep a local email → cativa_user_id table populated by Cativa’s user_created webhook. Every time someone joins the community, you save the row. When the purchase arrives, you look up locally with no API call.
Case B — the buyer does not have a Cativa account yet: you need them to sign up first.
User creation directly via partner API Key is coming soon. Workaround today: send an email with the tenant’s sign-up link plus a note that the badge will be granted once they join. When they sign up, the user_created webhook lands on your server and you complete the flow (see step 4).
async function inviteBuyer({ email, productId, purchaseId }) { // Save the grant intent to complete it when user_created arrives await db.pendingGrants.insert({ email, productId, purchaseId, createdAt: new Date() }); // Send email with the tenant's sign-up link await mailer.send({ to: email, subject: 'Your access to Premium Course', text: `Sign up at https://{customerName}.cativa.digital/signup?email=${encodeURIComponent(email)} to unlock your access.` });}
3
Assign the badge
Map the gateway productId to the Cativa badgeId configured in the Console.
Badge assignment via partner API Key is coming soon. Today, assigning/removing badges happens in the Console (manually or via import) or through internal platform flows. When the public endpoint is available, this page will be updated with the full cURL. To unblock your case in the meantime, open a ticket at dev@cativa.digital.
Mental sketch of what it’ll look like:
const PRODUCT_TO_BADGE = { 'hotmart_product_123': 'badge_uuid_premium', 'hotmart_product_456': 'badge_uuid_mentoring_2026'};async function handlePurchase({ email, productId, purchaseId }) { const badgeId = PRODUCT_TO_BADGE[productId]; if (!badgeId) { console.warn(`No badge mapped for product ${productId}`); return; } const cativaUserId = await resolveCativaUserId(email); if (!cativaUserId) { await inviteBuyer({ email, productId, purchaseId }); return; } // When the endpoint is available: const res = await fetch( `https://apis.cativalab.digital/social/v1/.../badges/${badgeId}/users/${cativaUserId}`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` } } ); if (!res.ok) throw new Error(`Badge assign failed: ${res.status}`); await db.purchases.insert({ purchaseId, cativaUserId, badgeId, grantedAt: new Date() });}
Cativa guarantees that assigning the same badge twice is idempotent (see Badges as Permissions) — so retries caused by timeouts or gateway redelivery do not double-grant.
4
(Optional) React to the user_received_badge webhook
Cativa fires user_received_badge every time a badge is assigned (regardless of whether it came from the API, Console, or another flow). Subscribe a listener to it if you want to:
When the gateway cancels or charges back, you want to remove the badge to revoke access.
async function handleCancellation({ email, productId, purchaseId }) { const badgeId = PRODUCT_TO_BADGE[productId]; if (!badgeId) return; const cativaUserId = await resolveCativaUserId(email); if (!cativaUserId) return; // When the endpoint is available: await fetch( `https://apis.cativalab.digital/social/v1/.../badges/${badgeId}/users/${cativaUserId}`, { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` } } ); await db.purchases.update({ purchaseId }, { revokedAt: new Date() });}
Badge removal via partner API Key is on the same waitlist as assignment. Same workaround: today it’s done in the Console; the public endpoint is shipping soon.
Removing the badge is enough — group, course and space access tied to the badge disappears immediately.
Buyer doesn't have a Cativa account, paid and ended up without access
Most common case. The customer bought on Hotmart before joining your community.Fix: step 2 above covers it — register the intent in pendingGrants and send the invite. Subscribe the user_created webhook and, when sign-up happens, complete the assignment:
Different email between gateway and Cativa for the same user
Happens when the customer pays with a personal email and joins the community with a corporate one. No automatic fix.Fix: offer an “I already bought, but I’m logged in with a different email” page in your app where the customer enters the purchase email. You validate the purchase ID locally and assign the badge to the logged-in user (not to the purchase email).
Gateway webhook fired twice — did the user get the badge twice?
Badge assignment in Cativa is idempotent: applying the same badge twice produces the same final state. But for safety, store the gateway purchaseId in a local table and check before:
if (await db.purchases.exists({ purchaseId })) { return; // already processed}
This also helps audit/reconcile later (e.g. financial report vs grants).
Gateway offers "recurring subscription" — how do I handle monthly renewal?
Each gateway fires a webhook when the renewal is charged successfully (e.g. Hotmart SUBSCRIPTION_CHARGE_SUCCESS). Treat it as an idempotent handlePurchase — re-apply the badge (no effect if already there). If the renewal fails (e.g. card declined), treat it as handleCancellation.
Customer refunded in < 7 days but kept using the community
You need to react to chargeback fast — the gateway webhook arrives, you remove the badge, access to the resources tied to it disappears. Don’t rely on a nightly batch job for this.
Multiple badges for the same product (course + bonus)
Map a product to multiple badges when needed. Example: product Premium Course unlocks both Premium (course access) and Mentoring-2026 (mentoring group access). Make two assignments inside handlePurchase.