@stubvia/checkout-react

Embedded Stubvia checkout for web React apps (iframe + postMessage).

App nativo (React Native, Flutter): use uma WebView nativa com ?webview=1 na URL do checkout e intercepte o deep link de retorno pós-compra. Este pacote não roda em React Native (depende de iframe no DOM). Ver Integração via API — Checkout in-app no site Stubvia.

Integration modes

| | Web (this package) | Native app (WebView) | | --- | --- | --- | | URL param | embed=1&parentOrigin=https://your-site.com | webview=1 | | StubVia config | checkoutEmbedOrigins allowlist | checkoutReturnUrlAllowlist (deep link) | | Parent communication | postMessage (ready, paid, error) | Intercept return deep link navigation | | Branding | checkoutEmbedBranding | Same checkoutEmbedBranding |

Both in-app modes hide the Stubvia site header and show optional org branding plus a Powered by Stubvia footer.

Install

npm install @stubvia/checkout-react

Prerequisites

1. Create the event in Stubvia and obtain event.checkoutUrl (or a signed checkout link).
2. In Stubvia dashboard → Área do desenvolvedor → Checkout embutido, add your site origin (e.g. https://app.exemplo.com).
3. For integrator-linked events, use a signed checkout URL (buildSignedCheckoutUrl from @stubvia/client).

Usage

import { StubviaCheckout } from "@stubvia/checkout-react";

export function BuyTicket({ checkoutUrl }: { checkoutUrl: string }) {
  return (
    <StubviaCheckout
      checkoutUrl={checkoutUrl}
      parentOrigin="https://app.exemplo.com"
      onReady={() => console.log("checkout ready")}
      onPaid={({ orderId }) => console.log("paid", orderId)}
      onError={({ message, code }) => console.error(code, message)}
      height={760}
    />
  );
}

Events

| Callback | When | | --- | --- | | onReady | Checkout iframe loaded and ready | | onPaid | Pix payment confirmed (orderId) | | onError | Validation, embed allowlist, or checkout error | | onCancelled | Reserved for future explicit cancel UX |

Messages use postMessage with source: "stubvia-checkout". The component validates event.origin against the checkout URL host.

Branding (v2)

Configure in Stubvia dashboard → Checkout embutido (applies to iframe embed and native webview=1):

• Logo URL (HTTPS) shown above the ticket
• Primary color (#RRGGBB) for sidebar, borders and buttons
• Font (sans, serif, or system)

The footer Powered by Stubvia always remains. Full white-label is a future plan tier.

Via API:

PATCH /api/v1/organization/integrator
{
  "checkoutEmbedBranding": {
    "logoUrl": "https://cdn.exemplo.com/logo.png",
    "primaryColor": "#2563eb",
    "fontFamily": "sans"
  }
}

Without React

Append embed params manually:

import { appendCheckoutEmbedParams } from "@stubvia/checkout-react";

const iframeSrc = appendCheckoutEmbedParams(checkoutUrl, "https://app.exemplo.com");

Listen for { source: "stubvia-checkout", type: "paid", orderId } on window.message.

Native WebView (not this package)

Append webview=1 to the signed checkout URL before loading it in a native WebView:

const url = new URL(signedCheckoutUrl);
url.searchParams.set("webview", "1");
// load url.toString() in WebView; intercept myapp://…?paid=1 on navigation

Configure checkoutReturnUrlAllowlist with your post-purchase deep link template.

Webhooks

Use order.paid webhooks (@stubvia/client) as the source of truth for backend sync. Iframe callbacks are for immediate UI updates in the parent page. The same applies to native apps after intercepting the return deep link.