Embedding the TransFi Checkout Widget

The checkout widget is a hosted page. You do not bundle any TransFi JavaScript
into your site. Integration is two steps:

1. Create a payment link / invoice against the checkout API → you get back a
   ready-to-open url.
2. Open that URL for the buyer — by redirect, in a new tab, or in an iframe.

There is no client-side SDK and no postMessage bridge. Payment outcome is
delivered by redirecting the buyer to your successRedirectUrl /
failureRedirectUrl, and (for server-side truth) by webhooks.

1. Create a payment link

Create a per-transaction invoice against the checkout API. This requires an
authenticated checkout session with a write role (admin or developer).

Production checkout API base: https://checkout-server.transfi.com
(this is also the widget's NEXT_PUBLIC_API_URL). QA uses a separate host.

POST https://checkout-server.transfi.com/checkout/payment-link/invoice

{
  "paymentLinkId": "<an existing payment link id>",
  "amount": "100",
  "fiatAmount": "100",
  "name": "Order #1234",
  "description": "1x Annual plan",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "customerOrderId": "your-internal-order-id",
  "successRedirectUrl": "https://yourstore.com/checkout/success",
  "failureRedirectUrl": "https://yourstore.com/checkout/failed"
}

Response:

{
  "paymentUrl": "https://<WIDGET_HOST>/checkout/payment-link/<invoiceId>",
  "invoiceId": "<invoiceId>"
}

Open paymentUrl for the buyer.

Always use the paymentUrl returned by the API. The host is chosen
server-side per environment (TRANSFI_CHECKOUT_WIDGET_URL), so don't build the
URL yourself — the shape is {WIDGET_HOST}/checkout/payment-link/{id}.

2. Open the widget

a) Redirect (simplest)

// after creating the link/invoice
window.location.href = paymentUrl;

b) New tab / popup

window.open(paymentUrl, "_blank", "noopener");

c) Iframe (keep the buyer on your page)

<iframe
  src="PAYMENT_URL_FROM_API"
  title="TransFi Checkout"
  width="100%"
  height="720"
  style="border:0; max-width:480px;"
  allow="clipboard-write; payment"
></iframe>

Notes for the iframe:

• Size it for mobile first (around 480px wide); the widget is responsive.
• clipboard-write lets buyers copy wallet addresses / references for crypto payments.
• On success or failure the widget navigates itself to your
  successRedirectUrl / failureRedirectUrl, so that redirect happens inside the
  iframe. If you need the top window to navigate, pass a redirect URL that is a
  thin page on your domain which breaks out of the frame, or prefer the redirect
  / new-tab method above.

3. Handle the result

• Buyer-facing: the widget redirects to the successRedirectUrl /
  failureRedirectUrl you set when creating the link. If you omit them, it falls
  back to a server-configured default.
• Server-side (authoritative): do not trust the browser redirect as proof
  of payment. Use checkout webhooks to confirm the final status before
  fulfilling the order. Match on the customerOrderId you supplied.