Skip to main content

Embedded Fields — embedded payment fields

Embedded Fields puts the card field inside your checkout page as a secure iframe: card data flows to the gateway without touching your server or your DOM. Everything outside the iframe is your page; inside it you control the look through a theme and style allowlist.

Two render modes: embed vs elements​

The mode is set per session via integrationMode:

  • embed (default) — one combined card box renders the whole payment surface (card + cardholder, billing address, eligible Apple Pay / Google Pay, and a returning buyer's saved cards). You place only email and save-for-future-use.
  • elements — you place the card, email, cardholder, address and other pieces as discrete elements where your account supports it; the card can stay the combined box or split into card-number / card-expiry / card-cvc. An elements session your account cannot render falls back to embed silently — read the integrationMode echoed on the created session.

Render modes: embed vs elements has the capability matrix; Build a custom checkout covers setting integrationMode and branching on the echoed value. The alternative to both is hosted checkout, where the buyer is redirected to checkout.vonpay.com.

Pages in this section​

  • Quickstart — end-to-end card-only integration
  • Build a custom checkout — opt a session into discrete elements rendering, and the fallback to embed
  • Customize the look & feel — interactive playground, three reference themes, the style allowlist
  • Render modes: embed vs elements — the two modes, the per-binder capability matrix, the silent fallback
  • Element reference — Card, Email, Save-for-future-use, discrete card fields; Apple Pay & Google Pay render inside the card mount when the device and your domain are eligible; a returning buyer's saved cards appear inside the embed when the session has a buyer
  • Tokenization & charge-and-save — what submit() returns and the reuse rules of the token you get back
  • Charge at submit — charging on the first submit in elements mode (CVV / AVS / 3-D Secure on the first charge)
  • Error handling — VoraMirrorError codes and recovery
  • 3D Secure — the challenge by redirect, and what to do while a payment is still processing

Does submit() charge?​

It depends on the session and on your account's binder, so read the result, not your configuration: in embed mode on a processor that charges inside the embed, a payment session charges on submit and, with a buyer attached, also vaults a reusable vp_pmt_* — calling /v1/payment_intents for that session double-charges; in elements mode submit() vaults and you charge server-side unless the session opted into charge at submit. Branch error → chargeStatus → token / charged — { charged: true } with no token is a guest charge — and confirm settlement via the webhook before fulfilling; never mark an order failed on a client-side error, and never resubmit blindly. Full contract: Tokenization & charge-and-save.

Server-side reference​

The payment lifecycle (/v1/payment_intents, capture, refund, void, webhooks) is shared with hosted checkout: Create session · Payment intents · Webhooks.