Skip to main content

Embedded Fields — embedded payment fields

Drop Embedded Fields into your checkout and your buyer's card information flows directly to the gateway — never touching your server, never landing in your DOM. The iframe sits inside your form, styled to match, but the card data reflects straight through to the processor on the other side. You keep full branding control of the page; we keep you out of PCI scope.

This is the embedded path. The alternative is hosted checkout — buyer redirects to checkout.vonpay.com. Embedded Fields gives you full branding control; hosted is faster to integrate.

Pages in this section​

  • Quickstart — end-to-end card-only integration in ~10 minutes
  • Customize the look & feel — interactive playground, three reference themes, the style allowlist, and what's stylable vs not
  • Elements reference — Card, Email, Save-for-future-use; Apple Pay & Google Pay render automatically inside the card mount when the buyer's device and your domain are eligible. Saved methods coming soon.
  • Using React — <VoraProvider>, <CardField>, useVora() patterns + the imperative elements API
  • Charge-and-save — the embed that charges on submit and optionally vaults a reusable payment method in one step; the { charged: true } result, buyer-vs-guest split, and confirm-via-webhook rule
  • Error handling — VoraMirrorError codes and recovery
  • 3D Secure — modal harmonization, disable3dsModal opt-out, confirmPaymentIntent + handleAction flows, test cards

Working sample​

samples/frame-react in the SDK repo is the canonical end-to-end reference — Express server stub for /api/create-session plus a React app using @vonpay/vora-react. Clone, fill in .env, pnpm dev.

Server-side reference​

The server-side payment lifecycle (/v1/payment_intents, capture, refund, void, MIT, webhooks) is shared with the hosted-checkout flow:

Two embed behaviors — wire your server accordingly.

  • Tokenize-only: submit() returns a vp_pmt_* token and charges nothing. Pair it with Payment intents to charge the saved method server-side.
  • Charge-and-save: the embed charges on submit and (with a buyer on the session) also vaults a reusable vp_pmt_* in one step. Do not call /v1/payment_intents for that session — doing so double-charges the buyer. The client result is a UX signal; confirm settlement via the webhook before fulfilling. See Charge-and-save.