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"
    }
  }'

const response = await fetch('https://api.stablegenius.co/v1/payment-intents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_abc123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 4.50,
    currency: 'usd',
    merchant_id: 'mer_abc123',
    metadata: {
      order_id: 'order_456',
      terminal_id: 'pos_01',
    },
  }),
});

const paymentIntent = await response.json();

import requests

response = requests.post(
    'https://api.stablegenius.co/v1/payment-intents',
    headers={
        'Authorization': 'Bearer sk_test_abc123',
        'Content-Type': 'application/json',
    },
    json={
        'amount': 4.50,
        'currency': 'usd',
        'merchant_id': 'mer_abc123',
        'metadata': {
            'order_id': 'order_456',
            'terminal_id': 'pos_01',
        },
    },
)

payment_intent = response.json()

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

Getting Started

Core Concepts

Integration Guides

Resources

Quickstart

Quickstart

Prerequisites

Step 1: Create a Payment Intent

Response

Step 2: Display the QR Code

Step 3: Receive the Webhook

Next Steps

Payment Intents

Webhooks

Testing

POS Integration

​Quickstart

​Prerequisites

​Step 1: Create a Payment Intent

​Response

​Step 2: Display the QR Code

​Step 3: Receive the Webhook

​Next Steps

Payment Intents

Webhooks

Testing

POS Integration

Quickstart

Prerequisites

Step 1: Create a Payment Intent

Response

Step 2: Display the QR Code

Step 3: Receive the Webhook

Next Steps