# Native Stripe checkout in conversations

Source: https://frosvo.com/docs/native-stripe-checkout
Updated: 2026-11-08

Configure your own Stripe account, send hosted checkout requests and understand verified payment status and retries.

Native Stripe checkout creates a payment session in your own Stripe account for a specific conversation and amount. Choose a hosted payment page or a native Stripe payment dialog opened from website chat alongside [payment requests in chat](/docs/payment-requests-in-chat) and [visitor order and service tracking](/docs/visitor-order-and-service-tracking). Your customer's money is processed by your merchant account, separately from your [Frosvo subscription](/docs/billing).

This flow requires the native-checkout database upgrade and application release. Your operator should complete real Stripe sandbox and full application/browser acceptance before enabling it for customers. Hosted checkout opens Stripe in another tab. Embedded checkout uses Stripe's own component in a dialog on the customer's top-level website, outside the chat iframe.

## Connect your Stripe account

1. Open **Settings → Integrations → Merchant checkout & payment requests** as a workspace owner.
2. Save your merchant display name and your own Stripe secret API key. Start with a test-mode key. Keys are sealed at rest; never paste them into a conversation or help article.
3. Copy the **Native Stripe webhook endpoint** displayed underneath the form.
4. In your Stripe account, create a webhook endpoint for that address and select `checkout.session.completed` and `checkout.session.async_payment_succeeded`.
5. Copy Stripe's endpoint signing secret, beginning with `whsec_`, into **Native Stripe webhook signing secret**, then save.
6. Verify a signed test delivery in Stripe and a complete test checkout before using live credentials. Test and live modes need their matching merchant keys, endpoints and signing secrets.

The custom merchant webhook endpoint and its Frosvo-generated signing secret belong to the existing payment-link integration. They are different from Stripe's native endpoint and signing secret. Do not interchange them. A publishable key is required for embedded checkout and is not needed for hosted checkout.

## Request a payment

1. Open the customer's conversation and choose **Request payment**.
2. Choose **Create Stripe checkout with my merchant account**.
3. Enter the order reference, title, amount, currency and optional note. Confirm the details before submitting.
4. Send the payment card. Native checkout is valid for 24 hours by default.
5. The customer opens the secure Stripe page and returns to the conversation after checkout.

The amount and currency are fixed when the checkout operation is first saved. Changing the form after an uncertain submission cannot change that operation. Review the existing purchase before intentionally starting a replacement.

## Offer checkout from website chat

1. Save the publishable key from the same Stripe account and mode as your secret key. Enable **native Stripe payment dialogs from website chat**.
2. Update your website to the current Frosvo `w.js` embed script. The payment add-on loads only when a customer chooses to pay; Stripe's SDK loads when needed.
3. In a website conversation, select **Stripe checkout inside website chat** and send the card. Other channels use hosted checkout.
4. The customer chooses **Pay in chat**. Frosvo verifies the exact visitor, site, conversation and payment request, then opens Stripe's component in a top-level payment dialog. Redirect-based payment methods are disabled for this session type.
5. Closing the dialog or changing the chat identity destroys the component. A completion notice means submission; the chat shows Paid after server verification of Stripe's session.

No arbitrary hosted payment page is placed in an iframe. Embedded checkout needs a top-level customer website, a supported browser and a compatible Stripe SDK. If your website already loads an incompatible Stripe version or its content policy blocks Stripe, the dialog reports an error instead of replacing your existing SDK. Review [Stripe's embedded checkout setup](https://docs.stripe.com/checkout/embedded/quickstart) with your website developer.

Client secrets stay in the authorized browser flow and are not added to checkout URLs, browser storage or logs. The dialog is marked as Frosvo UI so Frosvo's recording/co-browse snapshots omit it. Native mobile webviews and a standalone chat preview do not provide the top-level website bridge; use hosted checkout for those contexts.

## How payment confirmation works

A browser return or a completion event alone does not prove payment. Frosvo retrieves the Checkout Session from Stripe, checks the merchant, workspace, request, session identity, amount, currency and expiry, and only marks it paid when the verified session is complete and paid.

Payment status and its chat reply commit together. Repeated completion deliveries cannot produce a second status transition. A provider outage or configuration change can leave confirmation pending; inspect webhook deliveries and retry the existing event after resolving the problem.

For published native checkouts, owners use **Check Stripe status** in the conversation's payment panel. This retrieves the saved session and validates its financial identity. A verified complete-and-paid session can mark the request paid; a verified expired session can mark an open request expired. Complete-but-unpaid stays pending, and an open unpaid session is not payment confirmation. The check and any resulting payment/reply update are audited together. Permission changes, changed credentials or stale payment details refuse the check; choose **Reload** before reviewing again.

Manual **Mark paid**, **Cancel** and **Mark refunded** controls apply to external payment links only. Native checkout refuses those local overrides, including custom merchant callbacks without native verification. This status check does not create a new session, recover an unpublished uncertain operation, reconcile refunds, cancel a processor session or prove bank settlement. Native refund reconciliation and processor cancellation remain separate implementation work. A channel that currently refuses the confirmation reply can also prevent its local payment update; resolve that review rather than starting another checkout.

## Retry safely

If submission reports an uncertain outcome, keep the same request and details and retry. Frosvo saves the original session parameters and reuses the creation key. Another in-flight attempt is refused until its lease expires. Reopening a published request returns the committed identity.

After the safe automatic retry window, or after a merchant credential change, the operation requires reconciliation. Check your Stripe account for the original session and purchase before creating a new request. Never assume a timeout means no payment or no session exists.

## Operator rollout

Apply `prisma/merchant-checkout-operations.sql` before starting upgraded application writers. It expands stored hosted URLs, creates the checkout-operation ledger and creates sealed native Stripe settings. Run the schema preflight and isolated database acceptance suite. Do not run test suites against customer data.

Keep all application writers on the same version. The operation ledger binds a credential generation and uses database UTC leases; old or replaced workers cannot publish a stale provider result. Workspace and conversation deletion remove their operations through foreign keys. No provider keys, client secrets or raw webhook payloads should appear in logs.

## Common questions

### Does Frosvo process payments through its own Stripe account?

No. Native Stripe checkout creates a Checkout Session in your own Stripe merchant account using your sealed Stripe secret key.

### How does Frosvo verify that a Stripe checkout was paid?

Frosvo verifies signed Stripe webhooks and retrieves the Checkout Session from Stripe to confirm the merchant, workspace, request, amount, and paid status.
