10 examples

Complete examples for common integration scenarios.

---

Backend API Integration

Node.js / Express - Stablix Client

// lib/stablix.js
const STABLIX_API = 'https://api.stablix.xyz/api/v1';
const API_KEY = process.env.STABLIX_SECRET_KEY;

async function stablixRequest(method, endpoint, data = null) {
  const response = await fetch(`${STABLIX_API}${endpoint}`, {
    method,
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: data ? JSON.stringify(data) : null
  });
  
  const result = await response.json();
  if (!result.success) throw new Error(result.message);
  return result.data;
}

module.exports = {
  // Invoices
  createInvoice: (data) => stablixRequest('POST', '/invoices', data),
  getInvoice: (id) => stablixRequest('GET', `/invoices/${id}`),
  
  // Plans
  createPlan: (data) => stablixRequest('POST', '/plans', data),
  getPlan: (id) => stablixRequest('GET', `/plans/${id}`),
  listPlans: () => stablixRequest('GET', '/plans'),
  
  // Subscriptions
  createSubscription: (data) => stablixRequest('POST', '/subscriptions', data),
  getSubscription: (id) => stablixRequest('GET', `/subscriptions/${id}`),
  listSubscriptions: (params) => stablixRequest('GET', `/subscriptions?${new URLSearchParams(params)}`),
  cancelSubscription: (id, data) => stablixRequest('POST', `/subscriptions/${id}/cancel`, data)
};

---

Plan Management

Create a Plan

const stablix = require('./lib/stablix');

// Create a subscription plan
app.post('/api/admin/plans', async (req, res) => {
  const { name, amount, interval, trial_days } = req.body;
  
  const plan = await stablix.createPlan({
    name,
    description: `${name} subscription`,
    amount,
    interval,  // 'weekly', 'monthly', 'yearly'
    chains: ['solana', 'base'],
    currencies: ['USDC', 'USDT'],
    trial_days: trial_days || 0,
    buffer_hours: 24
  });
  
  // Save plan to your database
  await db.plans.create({
    stablix_plan_id: plan.plan_id,
    name: plan.name,
    amount: plan.amount,
    payment_url: plan.payment_url
  });
  
  res.json({
    plan_id: plan.plan_id,
    payment_url: plan.payment_url
  });
});

List Plans

app.get('/api/plans', async (req, res) => {
  const plans = await stablix.listPlans();
  
  res.json(plans.map(plan => ({
    id: plan.plan_id,
    name: plan.name,
    amount: plan.amount,
    interval: plan.interval,
    subscribers: plan.subscriber_count,
    payment_url: plan.payment_url
  })));
});

---

SaaS Subscription Integration

Complete Subscription Flow

const express = require('express');
const crypto = require('crypto');
const stablix = require('./lib/stablix');

const app = express();

// 1. Create subscription plans on startup
async function setupPlans() {
  const plans = [
    { name: 'Starter', amount: 9.99, interval: 'monthly', trial_days: 7 },
    { name: 'Pro', amount: 29.99, interval: 'monthly', trial_days: 14 },
    { name: 'Enterprise', amount: 99.99, interval: 'monthly', trial_days: 30 }
  ];
  
  for (const plan of plans) {
    const existing = await db.plans.findOne({ name: plan.name });
    if (!existing) {
      const created = await stablix.createPlan(plan);
      await db.plans.create({
        name: plan.name,
        stablix_plan_id: created.plan_id,
        payment_url: created.payment_url,
        amount: plan.amount
      });
      console.log(`Created plan: ${plan.name} → ${created.payment_url}`);
    }
  }
}

// 2. Get pricing page data
app.get('/api/pricing', async (req, res) => {
  const plans = await db.plans.find({ is_active: true });
  res.json(plans.map(p => ({
    name: p.name,
    amount: p.amount,
    payment_url: p.payment_url
  })));
});

// 3. Create subscription (if you want to pre-create for a user)
app.post('/api/subscribe', async (req, res) => {
  const { plan_name, email } = req.body;
  
  const plan = await db.plans.findOne({ name: plan_name });
  if (!plan) return res.status(404).json({ error: 'Plan not found' });
  
  // Create user record
  let user = await db.users.findOne({ email });
  if (!user) {
    user = await db.users.create({ email, status: 'pending' });
  }
  
  // Create subscription
  const subscription = await stablix.createSubscription({
    plan_id: plan.stablix_plan_id,
    subscriber_email: email,
    subscriber_external_id: user.id,
    metadata: { plan_name }
  });
  
  await db.users.update(user.id, {
    stablix_subscription_id: subscription.subscription_id
  });
  
  res.json({ approval_url: subscription.approval_url });
});

// 4. Handle webhooks
app.post('/webhooks/stablix',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    // Verify signature
    const signature = req.headers['x-stablix-signature'];
    const timestamp = req.headers['x-stablix-timestamp'];
    const payload = req.body.toString();
    
    const signedPayload = `${timestamp}.${payload}`;
    const expected = crypto
      .createHmac('sha256', process.env.STABLIX_WEBHOOK_SECRET)
      .update(signedPayload)
      .digest('hex');
    
    if (signature !== expected) return res.status(401).send('Invalid signature');
    
    const event = JSON.parse(payload);
    
    switch (event.event) {
      case 'subscription.approved':
        await handleApproved(event.data);
        break;
      case 'subscription.charged':
        await handleCharged(event.data);
        break;
      case 'subscription.charge_failed':
        await handleChargeFailed(event.data);
        break;
      case 'subscription.cancelled':
        await handleCancelled(event.data);
        break;
    }
    
    res.status(200).send('OK');
  }
);

// Webhook handlers
async function handleApproved(data) {
  const user = await db.users.findOne({
    stablix_subscription_id: data.subscription_id
  });
  if (!user) return;
  
  const isTrialing = data.status === 'trialing';
  
  await db.users.update(user.id, {
    status: isTrialing ? 'trialing' : 'active',
    subscription_status: data.status,
    trial_end: data.trial_end,
    access_until: data.trial_end || data.next_charge_at
  });
  
  await sendEmail(user.email, 'welcome', {
    plan_name: data.plan_name,
    trial_end: data.trial_end
  });
}

async function handleCharged(data) {
  const user = await db.users.findOne({
    stablix_subscription_id: data.subscription_id
  });
  if (!user) return;
  
  // Record payment
  await db.payments.create({
    user_id: user.id,
    amount: data.amount,
    charge_id: data.charge_id,
    tx_hash: data.escrow_tx_hash
  });
  
  // Extend access
  await db.users.update(user.id, {
    status: 'active',
    subscription_status: 'active',
    access_until: data.next_charge_at
  });
  
  await sendEmail(user.email, 'payment-received', {
    amount: data.amount,
    next_charge: data.next_charge_at
  });
}

async function handleChargeFailed(data) {
  const user = await db.users.findOne({
    stablix_subscription_id: data.subscription_id
  });
  if (!user) return;
  
  await db.users.update(user.id, {
    subscription_status: 'past_due'
  });
  
  await sendEmail(user.email, 'payment-failed', {
    retry_count: data.retry_count
  });
}

async function handleCancelled(data) {
  const user = await db.users.findOne({
    stablix_subscription_id: data.subscription_id
  });
  if (!user) return;
  
  await db.users.update(user.id, {
    status: 'cancelled',
    subscription_status: 'cancelled'
  });
  
  await sendEmail(user.email, 'subscription-cancelled', {
    reason: data.reason
  });
}

// 5. Cancel subscription
app.post('/api/subscriptions/:id/cancel', async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user?.stablix_subscription_id) {
    return res.status(404).json({ error: 'No subscription found' });
  }
  
  await stablix.cancelSubscription(user.stablix_subscription_id, {
    at_period_end: true,
    reason: req.body.reason || 'User requested'
  });
  
  await db.users.update(user.id, {
    cancel_at_period_end: true
  });
  
  res.json({ success: true });
});

// 6. Check access middleware
function requireSubscription(req, res, next) {
  const user = req.user;
  
  if (!user) return res.status(401).json({ error: 'Unauthorized' });
  
  if (!['active', 'trialing'].includes(user.status)) {
    return res.status(403).json({ 
      error: 'Subscription required',
      pricing_url: '/pricing'
    });
  }
  
  if (user.access_until && new Date(user.access_until) < new Date()) {
    return res.status(403).json({ 
      error: 'Subscription expired',
      pricing_url: '/pricing'
    });
  }
  
  next();
}

// Protected route
app.get('/api/premium-content', requireSubscription, async (req, res) => {
  res.json({ content: 'Premium data here' });
});

---

E-commerce Integration

One-Time Payments

// Create checkout for an order
app.post('/api/checkout', async (req, res) => {
  const { items, customer } = req.body;
  
  const total = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  
  // Create order
  const order = await db.orders.create({
    items,
    customer,
    total,
    status: 'pending'
  });
  
  // Create Stablix invoice
  const invoice = await stablix.createInvoice({
    amount: total,
    currency: 'USDC',
    chains: ['solana', 'base'],
    external_id: order.id,
    customer_email: customer.email,
    buffer_hours: 48,
    metadata: {
      order_id: order.id,
      items: items.map(i => i.name).join(', ')
    },
    redirect_url: `https://mystore.com/orders/${order.id}/success`
  });
  
  await db.orders.update(order.id, {
    stablix_invoice_id: invoice.invoice_id
  });
  
  res.json({
    order_id: order.id,
    payment_url: invoice.payment_url
  });
});

// Webhook: Order paid
async function handleInvoicePaid(data) {
  const order = await db.orders.findOne({
    stablix_invoice_id: data.invoice_id
  });
  if (!order) return;
  
  await db.orders.update(order.id, {
    status: 'paid',
    payment_tx: data.payment.tx_hash,
    paid_at: new Date()
  });
  
  // Start fulfillment
  await fulfillment.processOrder(order.id);
  
  await sendEmail(order.customer.email, 'order-confirmed', {
    order_id: order.id,
    items: order.items
  });
}

---

Python Integration

import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

STABLIX_API = 'https://api.stablix.xyz/api/v1'
API_KEY = os.environ['STABLIX_SECRET_KEY']
WEBHOOK_SECRET = os.environ['STABLIX_WEBHOOK_SECRET']

def stablix_request(method, endpoint, data=None):
    response = requests.request(
        method,
        f'{STABLIX_API}{endpoint}',
        headers={
            'X-API-Key': API_KEY,
            'Content-Type': 'application/json'
        },
        json=data
    )
    result = response.json()
    if not result['success']:
        raise Exception(result['message'])
    return result['data']

# Create a plan
@app.route('/api/plans', methods=['POST'])
def create_plan():
    data = request.json
    
    plan = stablix_request('POST', '/plans', {
        'name': data['name'],
        'amount': data['amount'],
        'interval': data['interval'],
        'trial_days': data.get('trial_days', 0)
    })
    
    return jsonify({
        'plan_id': plan['plan_id'],
        'payment_url': plan['payment_url']
    })

# Webhook handler
@app.route('/webhooks/stablix', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Stablix-Signature')
    timestamp = request.headers.get('X-Stablix-Timestamp')
    payload = request.get_data(as_text=True)
    
    signed_payload = f'{timestamp}.{payload}'
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    if signature != expected:
        return 'Invalid signature', 401
    
    event = request.json
    
    if event['event'] == 'subscription.charged':
        handle_subscription_charged(event['data'])
    elif event['event'] == 'invoice.paid':
        handle_invoice_paid(event['data'])
    
    return 'OK', 200

def handle_subscription_charged(data):
    print(f"Subscription {data['subscription_id']} charged ${data['amount']}")
    # Update your database

def handle_invoice_paid(data):
    print(f"Invoice {data['invoice_id']} paid")
    # Fulfill order

---

PHP Integration

<?php

class Stablix {
    private $apiKey;
    private $baseUrl = 'https://api.stablix.xyz/api/v1';
    
    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }
    
    private function request($method, $endpoint, $data = null) {
        $ch = curl_init();
        
        curl_setopt_array($ch, [
            CURLOPT_URL => $this->baseUrl . $endpoint,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'X-API-Key: ' . $this->apiKey,
                'Content-Type: application/json'
            ]
        ]);
        
        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        $result = json_decode($response, true);
        if (!$result['success']) {
            throw new Exception($result['message']);
        }
        return $result['data'];
    }
    
    // Plans
    public function createPlan($data) {
        return $this->request('POST', '/plans', $data);
    }
    
    // Subscriptions
    public function createSubscription($data) {
        return $this->request('POST', '/subscriptions', $data);
    }
    
    // Invoices
    public function createInvoice($data) {
        return $this->request('POST', '/invoices', $data);
    }
    
    // Verify webhook
    public function verifyWebhook($payload, $signature, $timestamp) {
        $signedPayload = $timestamp . '.' . $payload;
        $expected = hash_hmac('sha256', $signedPayload, $_ENV['STABLIX_WEBHOOK_SECRET']);
        return hash_equals($expected, $signature);
    }
}

// Usage
$stablix = new Stablix($_ENV['STABLIX_SECRET_KEY']);

// Create a plan
$plan = $stablix->createPlan([
    'name' => 'Pro Monthly',
    'amount' => 29.99,
    'interval' => 'monthly',
    'trial_days' => 14
]);

echo "Payment URL: " . $plan['payment_url'];

---

Webhook Testing

Test locally with ngrok

# Terminal 1: Start your server
npm run dev

# Terminal 2: Start ngrok
ngrok http 3000

# Copy the ngrok URL
# Set it as your webhook URL in Stablix dashboard

Test webhook handler

// test-webhook.js
const crypto = require('crypto');

const payload = JSON.stringify({
  event: 'subscription.charged',
  data: {
    subscription_id: 'sub_test123',
    plan_id: 'plan_test456',
    charge_id: 'chg_test789',
    amount: 29.99,
    next_charge_at: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString()
  },
  timestamp: new Date().toISOString()
});

const timestamp = Math.floor(Date.now() / 1000);
const signedPayload = `${timestamp}.${payload}`;
const signature = crypto
  .createHmac('sha256', process.env.STABLIX_WEBHOOK_SECRET)
  .update(signedPayload)
  .digest('hex');

fetch('http://localhost:3000/webhooks/stablix', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Stablix-Signature': signature,
    'X-Stablix-Timestamp': timestamp.toString()
  },
  body: payload
}).then(r => console.log('Status:', r.status));

---

Next Steps

• Plans — Create subscription products

• Subscriptions — Manage recurring billing

• Webhooks — Event handling reference

• API Reference — Complete endpoint documentation