Checkout sessions

Decide what the payer paysCopy Anchor Link

Send exactly one of these:

• price_id: an active one-time price on an active product, created in the dashboard. The price sets the amount.
• amount with description: a decimal USDC string from 0.01 to 1000000, with at most 6 decimals, such as "12.50". description is required with amount (up to 1,000 characters).

line_items (up to 50, each with a name, a quantity and an amount) are shown to the payer only. Fianto never adds them up or checks them against the amount, so they do not set what the payer pays.

Create the sessionCopy Anchor Link

mode, order_id (your own id, up to 128 characters), success_url and cancel_url are required. The URLs must be https, up to 2,048 characters. Unknown fields are refused with 400 validation_failed.

curl https://api.fianto.xyz/v1/checkout-sessions \
  --user "$FIANTO_APP_ID:$FIANTO_APP_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-order_1001-1" \
  -d '{
    "mode": "payment",
    "order_id": "order_1001",
    "amount": "12.50",
    "description": "Coffee beans, 1 kg",
    "success_url": "https://shop.example/thank-you",
    "cancel_url": "https://shop.example/cart"
  }'

Optional fields:

Send the payer to checkoutCopy Anchor Link

• Redirect (ui_mode: redirect): send the browser to url. After a success, checkout moves the payer to success_url after about 3 seconds. A cancel goes to cancel_url. An expired session stays on the checkout page. Fianto adds no query parameters to either URL.
• Popup (ui_mode: popup): open url in a popup with @fianto/js or @fianto/react. When the payer succeeds, cancels or the session expires, the popup posts { type: 'fianto.checkout', session_id, status } to the origin of your success_url, then closes. Serve the page that opens checkout from that origin.

The SDK's checkout route helpers always create popup sessions. See the quickstart.

Fulfil the order from Fianto, not from the browserCopy Anchor Link

The checkout page shows the payer a success message once the payment is confirmed. Fianto marks the order PAID and the payment SUCCEEDED, and sends order.paid and checkout.session.completed, only once it is finalized.

Reissue or cancel the session when you need toCopy Anchor Link

Reissue the link with POST /v1/checkout-sessions/{id}/link (reissueLink in the SDK). It returns a new url and the old link stops working. Fianto refuses when the session is not open or has less than 120 seconds left (session_not_reissuable), when a payment is in progress or the last transaction prepared for the payer could still land (payment_in_progress), or when Fianto could not check Solana in time (checkout_unavailable, with Retry-After).

Cancel with POST /v1/checkout-sessions/{id}/cancel. Only an open session with no payment in progress can be cancelled. Fianto sends checkout.session.canceled; there is no order event, and the order stays PENDING. The payer can also cancel on the checkout page, with the same result.

import { Fianto } from '@fianto/sdk';

const fianto = new Fianto();

export async function newLink(sessionId: string) {
  const session = await fianto.checkoutSessions.reissueLink(sessionId);
  return session.url; // the old link no longer works
}

export async function cancelCheckout(sessionId: string) {
  await fianto.checkoutSessions.cancel(sessionId);
}

Both are POSTs, so the curl form needs an Idempotency-Key too.