E-commerce (físico + digital)

Cliente
  ↓ checkout (do seu jeito — 1-step, multi-step, hosted, headless)
  ↓ tokeniza cartão no @zhexio/zhex-js OU pede PIX/boleto
seu backend
  ↓ /api/checkout    cria Customer + PaymentIntent + confirma
  ↓ webhook /api/webhook   libera fulfillment quando succeeded
Zhex
  ↓ MockPaymentAdapter (test) ou adquirente real (live)

CREATE TABLE orders (
  id              text PRIMARY KEY,               -- ord_<uuid>
  customer_id     text,
  zhex_intent     text,                           -- pi_*
  status          text,                           -- 'pending' | 'paid' | 'failed' | 'refunded'
  amount          int,
  description     text,                           -- usa pra correlacionar UTM
  utm_source      text, utm_medium text, utm_campaign text,
  created_at      timestamptz DEFAULT now(),
  paid_at         timestamptz
);

CREATE TABLE order_items (
  order_id   text REFERENCES orders(id),
  sku        text,
  qty        int,
  unit_price int
);

import Zhex from '@zhexio/node';
const zhex = new Zhex(process.env.ZHEX_SECRET_KEY!);

app.post('/api/checkout', async (req, res) => {
  const {
    items,                  // [{ sku, qty }]
    bumpAccepted,           // boolean — checkbox no checkout
    paymentMethod,          // 'card' | 'pix' | 'boleto'
    token,                  // tok_* (só cartão)
    customer: customerData,
    utm = {},
  } = req.body;

  // Calcula total no backend (não confiar no front)
  const products = await db.products.findMany({
    where: { sku: { in: items.map((i) => i.sku) } },
  });
  let amount = items.reduce((sum, i) => {
    const p = products.find((p) => p.sku === i.sku)!;
    return sum + p.price_cents * i.qty;
  }, 0);

  if (bumpAccepted) {
    const bump = await db.products.findFirst({ where: { sku: 'BUMP_OFFER' } });
    amount += bump!.price_cents;
  }

  // 1. Customer (idempotente por email)
  const customer = await zhex.customers.create(
    customerData,
    { idempotencyKey: `customer:${customerData.email}` },
  );

  // 2. Order local em pending
  const orderId = `ord_${randomUUID()}`;
  await db.orders.create({
    data: {
      id: orderId,
      customer_id: customer.id,
      status: 'pending',
      amount,
      description: `${items.map((i) => i.sku).join(',')}${bumpAccepted ? '+bump' : ''}`,
      ...utm,
    },
  });

  // 3. PaymentIntent
  const intent = await zhex.paymentIntents.create(
    {
      amount,
      currency: 'brl',
      customer: customer.id,
      payment_method_types: [paymentMethod],
      description: `Pedido ${orderId}`,
    },
    { idempotencyKey: `intent:${orderId}` },
  );

  await db.orders.update({
    where: { id: orderId },
    data: { zhex_intent: intent.id },
  });

  // 4. Cartão: confirma agora. PIX/boleto: retorna next_action
  if (paymentMethod === 'card' && token) {
    const confirmed = await zhex.paymentIntents.confirm(intent.id, {
      payment_method: token,
    });
    return res.json({
      orderId,
      status: confirmed.status,
      nextAction: confirmed.next_action ?? null,
    });
  }

  return res.json({
    orderId,
    status: intent.status,
    nextAction: intent.next_action ?? null,         // PIX QR ou boleto code
  });
});

<button id="pix-btn">Pagar com PIX · R$ 49,90</button>
<div id="pix-result" hidden>
  <img id="qr" />
  <code id="copy-paste"></code>
</div>

<script type="module">
  document.getElementById('pix-btn').addEventListener('click', async () => {
    const r = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        items: [{ sku: 'tenis-42', qty: 1 }],
        paymentMethod: 'pix',
        customer: { email: 'cliente@x.com', name: 'João', document: '12345678900' },
      }),
    }).then((r) => r.json());

    if (r.nextAction?.type === 'pix_display_qr_code') {
      document.getElementById('qr').src = r.nextAction.pix_display_qr_code.image_url;
      document.getElementById('copy-paste').textContent = r.nextAction.pix_display_qr_code.copy_paste;
      document.getElementById('pix-result').hidden = false;
    }
  });
</script>

import Zhex, { ZhexWebhookSignatureError } from '@zhexio/node';
import express from 'express';

app.post(
  '/api/webhook',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    let event;
    try {
      event = Zhex.webhooks.constructEvent(
        req.body,
        req.headers['zhex-signature'] as string,
        process.env.ZHEX_WEBHOOK_SECRET!,
      );
    } catch (err) {
      if (err instanceof ZhexWebhookSignatureError) {
        return res.status(400).send(`Invalid: ${err.message}`);
      }
      throw err;
    }

    // Dedup at-least-once
    const inserted = await db.processedEvents
      .insert({ id: event.id })
      .onConflict()
      .ignore();
    if (!inserted) return res.json({ received: true });

    if (event.type === 'payment_intent.succeeded') {
      const intent = event.data.object;
      const order = await db.orders.findFirst({ where: { zhex_intent: intent.id } });
      if (!order) return res.json({ received: true });

      await db.orders.update({
        where: { id: order.id },
        data: { status: 'paid', paid_at: new Date() },
      });

      // Fulfillment (físico ou digital — sua decisão)
      await fulfillmentQueue.add('order_paid', { orderId: order.id });

      // Email (recipe webhook-email)
      await emailQueue.add('order_paid', { orderId: order.id });

      // Server-side tracking pixel (Meta CAPI, GA4 MP)
      await reportPurchase(order);
    }

    if (event.type === 'payment_intent.payment_failed') {
      const intent = event.data.object;
      const order = await db.orders.findFirst({ where: { zhex_intent: intent.id } });
      if (order) {
        await db.orders.update({
          where: { id: order.id },
          data: { status: 'failed' },
        });
      }
    }

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

// Captura UTM no entrypoint da landing
app.get('/produto/:slug', async (req, res) => {
  const utm = {
    utm_source: req.query.utm_source,
    utm_medium: req.query.utm_medium,
    utm_campaign: req.query.utm_campaign,
  };
  res.cookie('utm', JSON.stringify(utm), {
    maxAge: 30 * 24 * 60 * 60 * 1000,
  });
  // ... renderiza produto
});

async function reportPurchase(order) {
  // Meta CAPI
  await fetch(
    `https://graph.facebook.com/v18.0/${process.env.FB_PIXEL_ID}/events`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        access_token: process.env.FB_CAPI_TOKEN,
        data: [{
          event_name: 'Purchase',
          event_time: Math.floor(Date.now() / 1000),
          action_source: 'website',
          user_data: {
            em: [hashSha256(order.customer_email)],
            ph: order.customer_phone ? [hashSha256(order.customer_phone)] : [],
          },
          custom_data: {
            currency: 'BRL',
            value: order.amount / 100,
            order_id: order.id,
          },
        }],
      }),
    },
  );

  // GA4 Measurement Protocol — análogo
}

app.post('/api/orders/:id/refund', async (req, res) => {
  const order = await db.orders.findUnique({ where: { id: req.params.id } });
  if (!order || order.status !== 'paid') {
    return res.status(400).json({ error: 'order_not_refundable' });
  }

  await zhex.refunds.create(
    {
      payment_intent: order.zhex_intent,
      reason: 'requested_by_customer',
    },
    { idempotencyKey: `refund:${order.id}` },
  );

  await db.orders.update({
    where: { id: order.id },
    data: { status: 'refunded' },
  });

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