Merchant site          Fex Pay Widget              Fex Backend            Customer's Fex App
──────────────         ─────────────────           ────────────           ──────────────────
FexPay.pay()    ──▶   POST /payment-intents  ──▶  Create intent
                       Show QR modal         ◀──   { qr_code_url, id }
                       Poll /payment-intents
                                                                   ◀──  Customer scans QR
                                                   status: completed ──▶
                       onSuccess callback    ◀──   Intent completed
FexPay.confirm()──▶   Show success screen

<script src="https://fex.app/widget/v1/fex-pay.js"></script>

<button id="checkout-btn">Pay with Fex</button>

<script src="/js/fex-pay.js"></script>
<script>
  // 1. Initialize once with your Merchant ID
  FexPay.init({
    merchantId: 'YOUR_MERCHANT_UUID',
  });

  // 2. Trigger a payment when the customer clicks Pay
  document.getElementById('checkout-btn').addEventListener('click', function () {
    FexPay.pay({
      amount: 49.99,
      currency: 'USD',
      description: 'Order #1042',
      onSuccess: function (intent) {
        console.log('Paid!', intent.id);
        window.location.href = '/order/success';
      },
      onError: function (err) {
        console.error('Payment failed:', err.message);
      },
      onCancel: function () {
        console.log('Customer closed the modal');
      },
    });
  });
</script>

FexPay.init({
  merchantId: '74815c83-e47b-4dc5-aefe-abe4484dd280',
  // baseUrl: 'https://staging-api.fex.app/merchant/api/v1', // optional
});

onSuccess: function (intent) {
  // intent.id         — payment intent UUID
  // intent.amount     — number
  // intent.currency   — string
  // intent.status     — "completed" | "paid"
  // intent.merchant_id
  // ...
}

onError: function (err) {
  // err.code     — one of: "VALIDATION" | "API_ERROR" | "TIMEOUT" | "PAYMENT_FAILED"
  // err.message  — human-readable description
  // err.status   — HTTP status code (API_ERROR only)
}

FexPay.pay({
  amount: 129.99,
  currency: 'USD',
  description: 'Pro subscription — annual plan',
  callbackUrl: 'https://yourshop.com/api/fex/webhook',
  onSuccess: function (intent) {
    // Redirect to a confirmation page
    window.location.href = '/checkout/complete?ref=' + intent.id;
  },
  onError: function (err) {
    if (err.code === 'TIMEOUT') {
      alert('Session expired. Please try again.');
    } else {
      alert('Payment error: ' + err.message);
    }
  },
  onCancel: function () {
    // Nothing — customer decided not to pay
  },
});

// Called inside your webhook listener on the client side
// (e.g. via WebSocket or Server-Sent Events from your server)
FexPay.confirm('a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11');

1. Customer clicks Pay                     → FexPay.pay({ callbackUrl: '...' })
2. Backend receives payment confirmation   → POST https://yourshop.com/api/fex/webhook
3. Your server validates the webhook
4. Your server pushes the intent ID to the client (WebSocket / SSE)
5. Client calls FexPay.confirm(intentId)   → modal shows success immediately

// POST /api/fex/webhook
app.post('/api/fex/webhook', (req, res) => {
  const { payment_intent } = req.body;

  if (payment_intent.status === 'completed') {
    // Update your order in the database
    fulfillOrder(payment_intent.id);

    // Push to the browser via WebSocket / SSE so the client can call FexPay.confirm()
    notifyClient(payment_intent.merchant_id, payment_intent.id);
  }

  res.json({ received: true });
});

const ws = new WebSocket('wss://yourshop.com/ws');

ws.addEventListener('message', function (event) {
  const msg = JSON.parse(event.data);
  if (msg.type === 'payment_confirmed') {
    FexPay.confirm(msg.paymentIntentId);
  }
});

const sse = new EventSource('/api/events');

sse.addEventListener('payment_confirmed', function (event) {
  const { paymentIntentId } = JSON.parse(event.data);
  FexPay.confirm(paymentIntentId);
});

# Serve locally — any static server works
npx serve widget/
# then open http://localhost:3000/demo.html