09 code Examples

Code Examples

Complete examples for common integration scenarios.

---

Checkout Widget (Easiest)

The fastest way to accept crypto payments. No backend required.

Basic HTML

<script src="https://api.stablix.xyz/js/checkout.js"></script>

<button onclick="pay()">Pay $49.99</button>

<script>
function pay() {
  StablixPay.setup({
    key: 'pk_live_your_public_key',
    amount: 49.99,
    currency: 'USDC',
    chain: 'solana',
    onSuccess: function(response) {
      alert('Payment successful!');
      window.location.href = '/thank-you?ref=' + response.invoice_id;
    }
  });
}
</script>

React / Next.js

// components/PayButton.jsx
import { useEffect } from 'react';

export default function PayButton({ amount, onSuccess }) {
  useEffect(() => {
    if (!window.StablixPay) {
      const script = document.createElement('script');
      script.src = 'https://api.stablix.xyz/js/checkout.js';
      document.body.appendChild(script);
    }
  }, []);

  const handleClick = () => {
    window.StablixPay.setup({
      key: process.env.NEXT_PUBLIC_STABLIX_KEY,
      amount,
      currency: 'USDC',
      chain: 'solana',
      onSuccess
    });
  };

  return (
    <button onClick={handleClick}>
      Pay ${amount} with Crypto
    </button>
  );
}

// Usage
<PayButton 
  amount={49.99} 
  onSuccess={(res) => router.push('/success?ref=' + res.invoice_id)} 
/>

Vue.js

<template>
  <button @click="pay">Pay ${{ amount }} with Crypto</button>
</template>

<script setup>
import { onMounted } from 'vue';

const props = defineProps(['amount']);
const emit = defineEmits(['success']);

onMounted(() => {
  if (!window.StablixPay) {
    const script = document.createElement('script');
    script.src = 'https://api.stablix.xyz/js/checkout.js';
    document.body.appendChild(script);
  }
});

function pay() {
  window.StablixPay.setup({
    key: import.meta.env.VITE_STABLIX_KEY,
    amount: props.amount,
    currency: 'USDC',
    chain: 'solana',
    onSuccess: (res) => emit('success', res)
  });
}
</script>

With Backend Verification

Always verify payments on your backend before delivering goods/services:

// Frontend
StablixPay.setup({
  key: 'pk_live_xxx',
  amount: 99.99,
  metadata: { orderId: 'order_123' },
  onSuccess: async (response) => {
    // Verify on your backend
    const result = await fetch('/api/verify-payment', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ invoice_id: response.invoice_id })
    });
    
    if (result.ok) {
      window.location.href = '/success';
    }
  }
});

// Backend (Node.js)
app.post('/api/verify-payment', async (req, res) => {
  const { invoice_id } = req.body;
  
  // Verify with Stablix using SECRET key
  const response = await fetch(
    `https://api.stablix.xyz/api/v1/invoices/${invoice_id}`,
    { headers: { 'X-API-Key': process.env.STABLIX_SECRET_KEY } }
  );
  
  const { data: invoice } = await response.json();
  
  if (invoice.status === 'paid') {
    // Fulfill the order
    await db.orders.update(invoice.metadata.orderId, { status: 'paid' });
    res.json({ success: true });
  } else {
    res.status(400).json({ error: 'Payment not confirmed' });
  }
});

---

Backend API Integration

For more control, use the API directly from your backend.

Node.js / Express

// stablix.js - Simple Stablix client
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 = {
  createInvoice: (data) => stablixRequest('POST', '/invoices', data),
  getInvoice: (id) => stablixRequest('GET', `/invoices/${id}`),
  listInvoices: (params) => stablixRequest('GET', `/invoices?${new URLSearchParams(params)}`),
  releaseInvoice: (id) => stablixRequest('POST', `/invoices/${id}/release`),
  refundInvoice: (id, reason) => stablixRequest('POST', `/invoices/${id}/refund`, { reason })
};

Usage

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

// Create checkout
app.post('/checkout', async (req, res) => {
  const { cart, customer_email } = req.body;
  
  const invoice = await stablix.createInvoice({
    amount: cart.total,
    currency: 'USDC',
    chain: 'solana',
    external_id: cart.id,
    customer_email,
    metadata: {
      items: cart.items.map(i => i.name).join(', ')
    },
    redirect_url: `https://mystore.com/orders/${cart.id}/success`
  });
  
  res.json({ payment_url: invoice.payment_url });
});

---

E-commerce Integration

Complete Checkout Flow

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

const app = express();

// 1. Create order and invoice
app.post('/api/checkout', async (req, res) => {
  const { items, customer } = req.body;
  
  // Calculate total
  const total = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  
  // Create order in your database
  const order = await db.orders.create({
    items,
    customer,
    total,
    status: 'pending'
  });
  
  // Create Stablix invoice
  const invoice = await stablix.createInvoice({
    amount: total,
    currency: 'USDC',
    chain: 'solana',
    external_id: order.id,
    customer_email: customer.email,
    buffer_hours: 48, // 48 hours for physical goods
    metadata: {
      order_id: order.id,
      customer_name: customer.name
    }
  });
  
  // Save invoice ID to order
  await db.orders.update(order.id, {
    stablix_invoice_id: invoice.invoice_id
  });
  
  res.json({
    order_id: order.id,
    payment_url: invoice.payment_url
  });
});

// 2. Handle webhook
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 expectedSignature = crypto
      .createHmac('sha256', process.env.STABLIX_WEBHOOK_SECRET)
      .update(signedPayload)
      .digest('hex');
    
    if (signature !== expectedSignature) {
      return res.status(401).send('Invalid signature');
    }
    
    const event = JSON.parse(payload);
    
    switch (event.event) {
      case 'invoice.paid':
        await handlePayment(event.data);
        break;
      case 'invoice.released':
        await handleRelease(event.data);
        break;
      case 'dispute.opened':
        await handleDispute(event.data);
        break;
    }
    
    res.status(200).send('OK');
  }
);

async function handlePayment(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()
  });
  
  // Send confirmation email
  await sendEmail(order.customer.email, 'order-confirmed', {
    order_id: order.id,
    items: order.items
  });
  
  // Start fulfillment
  await fulfillment.startShipping(order.id);
}

async function handleRelease(data) {
  const order = await db.orders.findOne({
    stablix_invoice_id: data.invoice_id
  });
  
  await db.orders.update(order.id, {
    status: 'completed',
    released_at: new Date()
  });
}

async function handleDispute(data) {
  const order = await db.orders.findOne({
    stablix_invoice_id: data.invoice_id
  });
  
  await db.orders.update(order.id, {
    status: 'disputed'
  });
  
  // Notify support team
  await slack.notify('#disputes', `New dispute for order ${order.id}`);
}

---

SaaS Subscription Integration

Subscription Management

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

// Create subscription plan
app.post('/api/subscribe', async (req, res) => {
  const { plan_id, wallet_address, email } = req.body;
  
  const plan = await db.plans.findById(plan_id);
  
  // Create user record
  const user = await db.users.create({
    email,
    wallet: wallet_address,
    plan_id,
    status: 'pending'
  });
  
  // Create Stablix subscription
  const subscription = await stablix.createSubscription({
    amount: plan.price,
    currency: 'USDC',
    chain: 'solana',
    interval: plan.interval, // 'monthly'
    subscriber_wallet: wallet_address,
    subscriber_email: email,
    trial_days: plan.trial_days || 0,
    external_id: user.id,
    metadata: {
      plan_name: plan.name,
      user_id: user.id
    }
  });
  
  await db.users.update(user.id, {
    stablix_subscription_id: subscription.subscription_id
  });
  
  res.json({
    approval_url: subscription.approval_url
  });
});

// Cancel subscription
app.post('/api/subscriptions/:id/cancel', async (req, res) => {
  const user = await db.users.findById(req.params.id);
  
  await stablix.cancelSubscription(user.stablix_subscription_id, {
    reason: 'User requested cancellation',
    immediate: false // Cancel at end of billing period
  });
  
  await db.users.update(user.id, {
    cancel_at_period_end: true
  });
  
  res.json({ success: true });
});

// Webhook handlers
async function handleSubscriptionCharged(data) {
  const user = await db.users.findOne({
    stablix_subscription_id: data.subscription_id
  });
  
  await db.payments.create({
    user_id: user.id,
    amount: data.amount,
    tx_hash: data.tx_hash,
    billing_cycle: data.billing_cycle
  });
  
  // Extend access
  await db.users.update(user.id, {
    access_until: data.next_billing_date
  });
}

async function handleSubscriptionFailed(data) {
  const user = await db.users.findOne({
    stablix_subscription_id: data.subscription_id
  });
  
  await sendEmail(user.email, 'payment-failed', {
    retry_date: data.next_retry_at
  });
}

---

Python Integration

Flask Example

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

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']

@app.route('/api/checkout', methods=['POST'])
def checkout():
    data = request.json
    
    invoice = stablix_request('POST', '/invoices', {
        'amount': data['amount'],
        'currency': 'USDC',
        'chain': 'solana',
        'external_id': data['order_id']
    })
    
    return jsonify({
        'payment_url': invoice['payment_url']
    })

@app.route('/webhooks/stablix', methods=['POST'])
def webhook():
    # Verify signature
    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'] == 'invoice.paid':
        handle_payment(event['data'])
    
    return 'OK', 200

def handle_payment(data):
    # Update your database
    print(f"Invoice {data['invoice_id']} paid!")

---

PHP Integration

<?php

class Stablix {
    private $apiKey;
    private $baseUrl = 'https://api.stablix.xyz/api/v1';
    
    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }
    
    public function createInvoice($data) {
        return $this->request('POST', '/invoices', $data);
    }
    
    public function getInvoice($id) {
        return $this->request('GET', "/invoices/{$id}");
    }
    
    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'];
    }
    
    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']);

$invoice = $stablix->createInvoice([
    'amount' => 99.99,
    'currency' => 'USDC',
    'chain' => 'solana'
]);

echo "Payment URL: " . $invoice['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 (e.g., https://abc123.ngrok.io)
# Set it as your webhook URL in Stablix dashboard

Verify webhook handling

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

const payload = JSON.stringify({
  event: 'invoice.paid',
  data: {
    invoice_id: 'inv_test123',
    amount: 99.99,
    currency: 'USDC',
    payment: {
      tx_hash: 'test_tx_hash',
      confirmed_at: new Date().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');

// Send test webhook
fetch('http://localhost:3000/webhooks/stablix', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Stablix-Signature': signature,
    'X-Stablix-Timestamp': timestamp.toString(),
    'X-Stablix-Event': 'invoice.paid',
    'X-Stablix-Delivery-ID': 'test_delivery_123'
  },
  body: payload
});

---

Next Steps

• API Reference — Complete endpoint documentation

• Webhooks — Webhook setup and event handling

• Testing — Test mode and sandbox environment