03 checkout Widget

The Stablix Checkout Widget lets you accept crypto payments with a single line of code. No npm package required — just add a script tag and start accepting USDC/USDT payments.

Quick Start

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

<button onclick="payWithStablix()">Pay $99.99</button>

<script>
function payWithStablix() {
  StablixPay.setup({
    key: 'pk_live_your_public_key',
    amount: 99.99,
    currency: 'USDC',
    chain: 'solana',
    onSuccess: function(response) {
      console.log('Payment successful!', response);
      window.location.href = '/success?ref=' + response.invoice_id;
    }
  });
}
</script>

That's it. The widget handles everything: QR code generation, wallet address display, payment detection, and confirmation.

Configuration Options

Parameter

Type

Required

Default

Description

key

string

Yes

Your public key (pk_live_xxx or pk_test_xxx)

amount

number

Yes

Payment amount in USD

currency

string

USDC

Token to accept: USDC or USDT

chain

string

solana

Blockchain: solana or base

email

string

Customer email for receipts

metadata

object

{}

Custom data (order ID, product info, etc.)

onSuccess

function

Called when payment is confirmed

onClose

function

Called when user closes the widget

onError

function

Called on initialization error

Callback Responses

onSuccess Response

{
  invoice_id: "inv_abc123def456",
  tx_hash: "5xYz...abc",
  amount: 99.99,
  currency: "USDC",
  chain: "solana",
  status: "paid"
}

onError Response

{
  message: "Error description"
}

Framework Examples

React / Next.js

import { useEffect } from 'react';

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

  const handlePayment = () => {
    window.StablixPay.setup({
      key: process.env.NEXT_PUBLIC_STABLIX_PUBLIC_KEY,
      amount: amount,
      currency: 'USDC',
      chain: 'solana',
      metadata: { orderId },
      onSuccess: (response) => {
        // Verify payment on your backend
        fetch('/api/verify-payment', {
          method: 'POST',
          body: JSON.stringify({ invoice_id: response.invoice_id })
        }).then(() => {
          window.location.href = '/order-confirmed';
        });
      },
      onClose: () => {
        console.log('Payment cancelled');
      }
    });
  };

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

Vue.js

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

<script>
export default {
  props: ['amount', 'orderId'],
  
  mounted() {
    if (!window.StablixPay) {
      const script = document.createElement('script');
      script.src = 'https://api.stablix.xyz/js/checkout.js';
      script.async = true;
      document.body.appendChild(script);
    }
  },
  
  methods: {
    payWithStablix() {
      window.StablixPay.setup({
        key: process.env.VUE_APP_STABLIX_PUBLIC_KEY,
        amount: this.amount,
        currency: 'USDC',
        chain: 'solana',
        metadata: { orderId: this.orderId },
        onSuccess: (response) => {
          this.$router.push('/success?ref=' + response.invoice_id);
        }
      });
    }
  }
}
</script>

Plain HTML (E-commerce)

<!DOCTYPE html>
<html>
<head>
  <title>Checkout</title>
  <script src="https://api.stablix.xyz/js/checkout.js"></script>
</head>
<body>
  <div class="product">
    <h2>Premium Plan</h2>
    <p>$49.99/month</p>
    <button id="pay-btn">Pay with Crypto</button>
  </div>

  <script>
    document.getElementById('pay-btn').addEventListener('click', function() {
      StablixPay.setup({
        key: 'pk_live_your_public_key',
        amount: 49.99,
        currency: 'USDC',
        chain: 'solana',
        email: document.getElementById('email').value,
        metadata: {
          plan: 'premium',
          customer_id: 'cust_123'
        },
        onSuccess: function(response) {
          // Send to your server to verify and activate subscription
          fetch('/api/activate', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
              invoice_id: response.invoice_id,
              tx_hash: response.tx_hash
            })
          }).then(function() {
            window.location.href = '/welcome';
          });
        },
        onClose: function() {
          console.log('User closed checkout');
        },
        onError: function(error) {
          alert('Payment error: ' + error.message);
        }
      });
    });
  </script>
</body>
</html>

How It Works

User clicks pay → Your code calls StablixPay.setup()
Widget opens → Modal appears with amount, QR code, and wallet address
Invoice created → Backend creates invoice using your public key
User sends crypto → Pays from their wallet (Phantom, MetaMask, etc.)
Payment detected → Widget polls for confirmation (every 3 seconds)
Callback fired → onSuccess called with transaction details
You verify → Your backend confirms payment via webhook or API

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Your      │     │   Stablix   │     │  Blockchain │
│   Website   │     │   Widget    │     │             │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       │ StablixPay.setup()│                   │
       │──────────────────>│                   │
       │                   │                   │
       │                   │ Create Invoice    │
       │                   │──────────────────>│
       │                   │                   │
       │    Show Modal     │<──────────────────│
       │<──────────────────│                   │
       │                   │                   │
       │                   │ User sends crypto │
       │                   │                   │
       │                   │ Poll for payment  │
       │                   │──────────────────>│
       │                   │                   │
       │                   │ Payment confirmed │
       │                   │<──────────────────│
       │                   │                   │
       │   onSuccess()     │                   │
       │<──────────────────│                   │
       │                   │                   │

Test Mode

Use your test public key (pk_test_xxx) to test without real payments:

StablixPay.setup({
  key: 'pk_test_your_test_key',  // Test mode
  amount: 10.00,
  onSuccess: function(response) {
    console.log('Test payment:', response);
  }
});

Test mode:

Creates real invoices (for testing your integration)
Uses testnet/devnet addresses
No real funds required

Customization

Custom API URL (Self-hosted)

// Set before calling setup()
StablixPay.setApiUrl('https://your-api.com/api/v1');

StablixPay.setup({
  key: 'pk_live_xxx',
  amount: 50
});

Security

Public Key Safety

Your public key (pk_live_xxx) is safe to expose in frontend code. It can only:

Create invoices
Check payment status

It cannot:

Access merchant data
Release funds
View transaction history
Modify settings

Always Verify Payments

Never trust the onSuccess callback alone. Always verify payments on your backend:

// Frontend
onSuccess: function(response) {
  // Send to your backend for verification
  fetch('/api/verify-payment', {
    method: 'POST',
    body: JSON.stringify({ invoice_id: response.invoice_id })
  });
}

// Backend (Node.js example)
app.post('/api/verify-payment', async (req, res) => {
  const { invoice_id } = req.body;
  
  // Call Stablix API with your 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 invoice = await response.json();
  
  if (invoice.data.status === 'paid') {
    // Deliver the product/service
    await deliverOrder(invoice.data.metadata.orderId);
    res.json({ success: true });
  } else {
    res.status(400).json({ error: 'Payment not confirmed' });
  }
});

Supported Browsers

The checkout widget supports all modern browsers:

Chrome (Desktop & Mobile)
Safari (Desktop & Mobile)
Firefox (Desktop)
Edge (Desktop)

Troubleshooting

// Check if script loaded
if (typeof StablixPay === 'undefined') {
  console.error('Stablix script not loaded');
}

// Check for errors
StablixPay.setup({
  key: 'pk_live_xxx',
  amount: 50,
  onError: function(error) {
    console.error('Stablix error:', error);
  }
});

Payment not detected

Ensure customer sent the exact amount
Ensure customer used the correct token (USDC vs USDT)
Ensure customer used the correct chain (Solana vs Base)
Check transaction on block explorer

CORS errors

If testing locally, ensure your backend allows CORS from localhost:

// Backend
app.use(cors({
  origin: ['http://localhost:3000', 'https://yourdomain.com']
}));

API Endpoints

The widget uses these endpoints internally:

Endpoint

Method

Auth

Description

/checkout/initialize

POST

X-Public-Key

Create invoice

/checkout/:id/status

GET

None

Poll payment status

You don't need to call these directly — the widget handles everything.

Previous02 authentication Next04 invoices

Last updated 3 days ago

Good afternoon

03 checkout Widget

Quick Start

Configuration Options

Callback Responses

onSuccess Response

onError Response

Framework Examples

React / Next.js

Vue.js

Plain HTML (E-commerce)

How It Works

Test Mode

Customization

Custom API URL (Self-hosted)

Security

Public Key Safety

Always Verify Payments

Supported Browsers

Troubleshooting

Widget doesn't open

Payment not detected

CORS errors

API Endpoints

Good afternoon

hashtagQuick Start

hashtagConfiguration Options

hashtagCallback Responses

hashtagonSuccess Response

hashtagonError Response

hashtagFramework Examples

hashtagReact / Next.js

hashtagVue.js

hashtagPlain HTML (E-commerce)

hashtagHow It Works

hashtagTest Mode

hashtagCustomization

hashtagCustom API URL (Self-hosted)

hashtagSecurity

hashtagPublic Key Safety

hashtagAlways Verify Payments

hashtagSupported Browsers

hashtagTroubleshooting

hashtagWidget doesn't open

hashtagPayment not detected

hashtagCORS errors

hashtagAPI Endpoints

Quick Start

Configuration Options

Callback Responses

onSuccess Response

onError Response

Framework Examples

React / Next.js

Vue.js

Plain HTML (E-commerce)

How It Works

Test Mode

Customization

Custom API URL (Self-hosted)

Security

Public Key Safety

Always Verify Payments

Supported Browsers

Troubleshooting

Widget doesn't open

Payment not detected

CORS errors

API Endpoints