Skip to main content

​
Quickstart

This guide walks you through creating a payment intent, rendering a QR code, and receiving a webhook when the customer pays. The entire integration is two API calls.
The Stable Genius API is currently in private beta. Request early access to get your API keys.

​
Prerequisites

  • A Stable Genius account with API keys (sk_test_... for sandbox, sk_live_... for production)
  • A merchant onboarded through the Stable Genius dashboard with KYC completed and bank account linked
  • Your webhook endpoint URL registered in the dashboard

​
Step 1: Create a Payment Intent

When a customer is ready to pay, create a payment intent. This returns a payment address and QR code payload that the customer scans with their wallet. 
curl -X POST https://api.stablegenius.co/v1/payment-intents \
  -H "Authorization: Bearer sk_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4.50,
    "currency": "usd",
    "merchant_id": "mer_abc123",
    "metadata": {
      "order_id": "order_456",
      "terminal_id": "pos_01"
    }
  }'

​
Response

{
  "id": "pi_xyz789",
  "object": "payment_intent",
  "status": "awaiting_payment",
  "amount": 4.50,
  "currency": "usd",
  "merchant_id": "mer_abc123",
  "payment_address": "0x1a2b3c4d5e6f...abcdef",
  "chain": "base",
  "token": "USDC",
  "qr_payload": "ethereum:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913@8453/transfer?address=0x1a2b3c4d5e6f...abcdef&uint256=4500000",
  "qr_image_url": "https://api.stablegenius.co/v1/qr/pi_xyz789.png",
  "expires_at": "2026-04-01T20:05:00Z",
  "metadata": {
    "order_id": "order_456",
    "terminal_id": "pos_01"
  },
  "created_at": "2026-04-01T20:00:00Z"
}

​
Step 2: Display the QR Code

Render the QR code on your terminal, app, or checkout page. You have two options: Option A: Render the QR payload yourself — Use qr_payload with any QR code library. This is the EIP-681 standard that wallets like Coinbase Wallet and MetaMask understand natively. Option B: Use our hosted QR image — Display qr_image_url directly as an image. No QR library needed. 
// Option A: Render with a QR library (e.g., qrcode.js)
import QRCode from 'qrcode';

const qrDataUrl = await QRCode.toDataURL(paymentIntent.qr_payload);
document.getElementById('qr').src = qrDataUrl;

// Option B: Use hosted image
document.getElementById('qr').src = paymentIntent.qr_image_url;
The customer scans the QR code with their wallet (Coinbase Wallet, MetaMask, Phantom, etc.), sees the pre-filled transfer, and taps confirm.

​
Step 3: Receive the Webhook

When the payment confirms on-chain, we send a payment_intent.confirmed event to your registered webhook URL: 
{
  "id": "evt_abc123",
  "object": "event",
  "type": "payment_intent.confirmed",
  "created_at": "2026-04-01T20:00:12Z",
  "data": {
    "id": "pi_xyz789",
    "object": "payment_intent",
    "status": "confirmed",
    "amount": 4.50,
    "currency": "usd",
    "net_amount": 4.455,
    "fee": 0.045,
    "merchant_id": "mer_abc123",
    "tx_hash": "0xabc123...def456",
    "chain": "base",
    "token": "USDC",
    "confirmed_at": "2026-04-01T20:00:12Z",
    "metadata": {
      "order_id": "order_456",
      "terminal_id": "pos_01"
    }
  }
}
Your system processes the webhook and marks the order as paid: 
app.post('/webhooks/stablegenius', (req, res) => {
  const event = req.body;

  // Verify webhook signature (see Webhook Security)
  // verifySignature(req);

  if (event.type === 'payment_intent.confirmed') {
    const { amount, tx_hash, metadata } = event.data;

    // Mark order as paid in your system
    markOrderPaid(metadata.order_id, {
      amount,
      tx_hash,
      paid_at: event.data.confirmed_at,
    });

    // Trigger your POS to show success (beep, receipt, etc.)
    notifyTerminal(metadata.terminal_id, 'payment_success');
  }

  res.status(200).json({ received: true });
});
That’s it. The merchant’s funds settle automatically to their bank account on the configured withdrawal schedule. You don’t manage wallets, watch blockchains, or handle settlements.

​
Next Steps

Payment Intents

Understand the full payment intent lifecycle

Webhooks

Learn about all webhook events and verification

Testing

Set up your sandbox environment

POS Integration

Build a terminal integration step-by-step