Quickstart

# Next.js
pnpm add @fianto/nextjs @fianto/react @fianto/sdk
# Express
pnpm add @fianto/express @fianto/js @fianto/sdk
# Hono
pnpm add @fianto/hono @fianto/js @fianto/sdk

// app/api/checkout/route.ts
import { Checkout } from '@fianto/nextjs';

// Prices live on your server.
const ITEMS: Record<string, { amount: string; description: string }> = {
  beans: { amount: '10.00', description: 'Coffee beans, 1 kg' },
};

export const POST = Checkout({
  createSession: async (request) => {
    const body = (await request.json().catch(() => null)) as { item?: string } | null;
    const item = body?.item ? ITEMS[body.item] : undefined;
    if (!item) return new Response('Unknown item', { status: 400 });

    return {
      mode: 'payment',
      order_id: `order_${crypto.randomUUID()}`, // use your own order's id
      amount: item.amount, // a decimal USDC string
      description: item.description, // required with amount
      success_url: 'https://shop.example/thank-you',
      cancel_url: 'https://shop.example/cart',
    };
  },
  onError: (error) => console.error(error),
});

// app/buy-button.tsx
'use client';

import { FiantoButton, fetchCheckoutSession } from '@fianto/react';
import { useState } from 'react';

// Never tell the payer "nothing happened": 'closed' means you do not know.
const MESSAGES: Record<string, string> = {
  succeeded: 'Thanks! We are confirming your payment.',
  canceled: 'Checkout canceled.',
  expired: 'That checkout link expired. Please try again.',
  closed: 'We could not tell what happened. Check your order status before paying again.',
};

export function BuyButton() {
  const [message, setMessage] = useState<string | null>(null);
  return (
    <div>
      <FiantoButton
        session={() => fetchCheckoutSession('/api/checkout', { body: { item: 'beans' } })}
        label="buy"
        onResult={(result) => setMessage(MESSAGES[result.status] ?? null)}
        onError={(error) => console.error(error)}
      />
      {message ? <p role="status">{message}</p> : null}
    </div>
  );
}

// app/api/webhooks/fianto/route.ts
import { Webhooks } from '@fianto/nextjs';

export const POST = Webhooks({
  secret: process.env.FIANTO_WEBHOOK_SECRET,
  onOrderPaid: async (event) => {
    // The same event can arrive more than once. Record event.id in the same
    // database transaction as the fulfilment, and skip ids you have already seen.
    console.log('paid', event.data.order_id, event.id);
  },
});