Quickstart
Start monetizing your application in 10 minutes. Choose the right SDK and follow step-by-step instructions for quick integration.
Choose the Right SDK
The platform provides three integration approaches to suit your needs:
| Mode | Advantages | Perfect for | Notes |
|---|---|---|---|
| Client-Side SDK — Recommended for Quick Start | Ready-made UI components; Built-in user authentication; Customizable themes and colors; Minimal integration effort; Automatic state management | Websites and SPAs; Chrome extensions; MVPs and rapid prototypes; Teams with limited frontend resources | — |
| Server-Side SDK — For Custom Solutions | Full control over user experience; Custom interface design; Complex business logic; Integration with existing systems | Custom platforms; Complex workflows; CRM/ERP integration; Mobile applications | Requires more work: you need to build your own interfaces and authentication logic |
| Hybrid Mode — Best of Both Worlds | Client SDK’s ready UI components; Server-side business logic control | Custom backend integration; Teams wanting UI flexibility with backend control | Requires more work: you need to build authentication logic |
Check out for our guides
Client-Side SDK
Get a working paywall in 5 minutes with ready-made components.
Step 1: Create Paywall
- Log into the dashboard
- Go to “Paywalls” → “New Paywall”
- Select “Client Mode”
- Fill in basic information:
- Paywall name
- Product name on checkout page
- Paywall title
- Support email
Step 2: Configure Pricing
- Click “Add Plan”
- Set price and period (month/year/lifetime)
- Add multiple plans if needed (с разными периодами оплаты)
- Mark recommended plan
Step 3: Create Payment Processor
- Go to “Payment Processors” → “New Payment Processor”
- Choose Stripe or Paddle
- Enter API keys (start with test mode)
- Save configuration
Step 4: Connect Processor to Paywall
- Open your paywall settings
- Go to “Payment Processor” tab
- Select the created payment processor
- Save changes
Step 5: Install SDK
- In paywall settings, click “Install”
- Copy the provided script
- Insert script into
<head>or beginning of<body>of your page:
<script>
// Your unique script will be here
// Copy the exact script from the dashboard
</script>Step 6: Use the SDK
Now you can use the paywall in your code:
// Open paywall
paywall.open();
// Get user information
const userInfo = await paywall.getUser();
if (userInfo.paid) {
// User has paid subscription
enablePremiumFeatures();
} else {
// Show limitations
showUpgradePrompt();
}
// Check token balance (for tokenized paywalls)
const tokens = userInfo.balances.find((b) => b.type === "standard");
if (tokens && tokens.count > 0) {
// User has tokens
allowAction();
}Ready-to-Use Examples
Basic Integration
// Simple integration
document.addEventListener('DOMContentLoaded', function() {
// Show paywall on button click
document.getElementById('upgrade-btn').addEventListener('click', function() {
paywall.open();
});
// Check user status on page load
checkUserStatus();
});
async function checkUserStatus() {
try {
const userInfo = await paywall.getUser();
if (userInfo.paid) {
document.body.classList.add('premium-user');
}
} catch (error) {
console.log('User not authenticated');
}
}
Server-Side SDK
Build custom interfaces with full control over UX.
Step 1: Create Paywall in Server Mode
- Log into the dashboard
- Create a new paywall, selecting “Server Mode”
- Configure basic information and pricing
- Create and connect payment processor
Step 2: Get API Keys
- Go to “Settings” → “API Keys”
- Create a new API key or copy existing one
- Find your paywall ID in its settings
Step 3: Get Price List
// Server function to get prices
async function getPaywallPrices(paywallId) {
const response = await fetch(
`https://onlineapp.pro/api/v1/paywall/${paywallId}/prices`,
{
method: "GET",
headers: {
"Content-Type": "application/json",
"x-api-key": process.env.PAYWALL_API_KEY,
},
}
);
const result = await response.json();
return result.data; // Array of prices
}Step 4: Create Checkout
// Server function to create payment
async function createCheckout(userEmail, priceId, paywallId) {
const response = await fetch(
`https://onlineapp.pro/api/v1/paywall/${paywallId}/start-checkout`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": process.env.PAYWALL_API_KEY,
},
body: JSON.stringify({
email: userEmail,
priceId: priceId,
successUrl: "https://yoursite.com/payment/success",
errorUrl: "https://yoursite.com/payment/error",
shopUrl: "https://yoursite.com/pricing",
trial_days: 7, // Optional
userMeta: {
source: "website",
campaign: "spring_sale",
},
}),
}
);
return response.json();
}Step 5: Setup Webhooks
// Webhook handler for payment tracking
app.post(
"/webhook/paywall",
express.raw({ type: "application/json" }),
(req, res) => {
const event = req.body;
switch (event.type) {
case "payment.completed":
// User successfully paid
console.log("Payment completed:", event.data);
activateUserSubscription(event.data.user.id);
break;
case "refund.created":
// Refund created
console.log("Refund created:", event.data);
handleRefund(event.data.user.id);
break;
case "subscription.cancelled":
// Subscription cancelled
deactivateUserSubscription(event.data.user.id);
break;
}
res.json({ received: true });
}
);Step 6: Create Interface
// Example React component for pricing page
import React, { useState, useEffect } from "react";
function PricingPage() {
const [prices, setPrices] = useState([]);
const [loading, setLoading] = useState(false);
useEffect(() => {
// Load prices from server
fetch("/api/prices")
.then((res) => res.json())
.then(setPrices);
}, []);
const handleSubscribe = async (priceId, planName) => {
setLoading(true);
try {
const response = await fetch("/api/create-checkout", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
priceId,
email: userEmail, // From your authentication system
planName,
}),
});
const data = await response.json();
if (data.checkoutUrl) {
window.location.href = data.checkoutUrl;
}
} catch (error) {
console.error("Checkout creation error:", error);
} finally {
setLoading(false);
}
};
return (
<div className="pricing-page">
<h1>Choose a Plan</h1>
<div className="pricing-grid">
{prices.map((price) => (
<div key={price.id} className="pricing-card">
<h3>{price.interval} plan</h3>
<p className="price">${price.unit_amount}</p>
<button
onClick={() =>
handleSubscribe(price.id, `${price.interval} plan`)
}
disabled={loading}
>
{loading ? "Creating..." : "Choose Plan"}
</button>
</div>
))}
</div>
</div>
);
}Complete Express.js Example
API Routes
// routes/paywall.js
const express = require('express');
const router = express.Router();
const PAYWALL_ID = process.env.PAYWALL_ID;
const API_KEY = process.env.PAYWALL_API_KEY;
// Get prices
router.get('/prices', async (req, res) => {
try {
const response = await fetch(`https://onlineapp.pro/api/v1/paywall/${PAYWALL_ID}/prices`, {
headers: {
'x-api-key': API_KEY
}
});
const result = await response.json();
res.json(result.data);
} catch (error) {
res.status(500).json({ error: 'Failed to fetch prices' });
}
});
// Create checkout
router.post('/create-checkout', async (req, res) => {
const { email, priceId, planName } = req.body;
try {
const response = await fetch(`https://onlineapp.pro/api/v1/paywall/${PAYWALL_ID}/start-checkout`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': API_KEY
},
body: JSON.stringify({
email,
priceId,
successUrl: `${req.protocol}://${req.get('host')}/payment/success`,
errorUrl: `${req.protocol}://${req.get('host')}/payment/error`,
shopUrl: `${req.protocol}://${req.get('host')}/pricing`,
userMeta: {
planName,
source: 'website'
}
})
});
const result = await response.json();
res.json(result);
} catch (error) {
res.status(500).json({ error: 'Failed to create checkout' });
}
});
Hybrid Mode
Build a flexible solution combining client-side UI with your server-side business logic.
Step 1: Create Paywall in Hybrid Mode
- Log into the dashboard
- Create a new paywall, selecting “Hybrid Mode”
- Configure basic information and pricing
- Create and connect payment processor
Step 2: Configure Server SDK Endpoints
- Set up your server endpoints that will handle paywall requests
- Configure the following in paywall settings:
- API base URL for your server
- Endpoints mapping for specific operations
Step 3: Install Client SDK
<script>
// Your unique script will be here
// Copy the exact script from the dashboard
</script>Step 4: Handle Client SDK Events
// Listen for paywall events
window.addEventListener("message", (event) => {
if (event.data.type === "PAYWALL_EVENT") {
const { event: eventType, payload } = event.data;
switch (eventType) {
case "purchase":
// Handle purchase event
handlePurchase(payload);
break;
case "restore":
// Handle restore subscription
handleRestore(payload);
break;
case "sign-out":
// Handle sign out
handleSignOut(payload);
break;
}
}
});
// Initialize paywall with user email (optional)
paywall.open({
email: "user@example.com", // Pre-fill email for authentication
});
// Example payload structure for purchase event:
// {
// paywallId: "wall_123",
// priceId: 456,
// priceCents: 1000,
// currency: "USD",
// interval: "month",
// localPriceCents: 1000,
// offerId: "offer_789"
// }Example Server Implementation
// Server-side purchase handler
async function handlePurchase(payload) {
const { paywallId, priceId, offerId } = payload;
try {
// Call your server endpoint
const response = await fetch("/api/process-purchase", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
});
// Your server uses Server SDK to process purchase
const result = await response.json();
if (result.success) {
// Purchase successful
showSuccessMessage();
}
} catch (error) {
handleError(error);
}
}
// Server endpoint using Server SDK
app.post("/api/process-purchase", async (req, res) => {
const { priceId, offerId } = req.body;
try {
// Use Server SDK to process purchase
const result = await fetch(
"https://onlineapp.pro/api/v1/paywall/PAYWALL_ID/start-checkout",
{
method: "POST",
body: JSON.stringify({
email,
paywallId,
priceId,
offerId,
}),
}
);
res.json({ success: true, data: result });
} catch (error) {
res.status(500).json({
success: false,
error: "Purchase processing failed",
});
}
});Key Benefits of Hybrid Mode
✨ Perfect Balance:
- Ready-made UI components from Client SDK
- Custom business logic with Server SDK
Useful Links
- Client-Side SDK: Full Documentation
- Server-Side SDK: API Reference
- Creating Paywall: Detailed Guide
- Payment Processors: Stripe/Paddle Setup
Need help? Join our Telegram community or contact support.