# Von Payments

> Von Payments is a multi-binder checkout platform: hosted checkout (`checkout.vonpay.com`) and Embedded Fields (in-page card fields) behind one merchant API. Server SDKs in Node + Python, browser SDK distributed via CDN, MCP server for AI agents, CLI for local dev. PCI scope-out by design — card data never touches merchant servers or DOM.

## Getting started

- [Overview](https://docs.vonpay.com/): what Von Payments is and how the two integration paths (hosted redirect vs embedded Mirror) compare
- [Quickstart — hosted redirect](https://docs.vonpay.com/integration/quickstart): cart → redirect to `checkout.vonpay.com`, signed-return verification, webhook handling
- [Embedded Fields quickstart](https://docs.vonpay.com/embedded-fields/quickstart): drop-in iframed card fields, ~10 minutes
- [How it works](https://docs.vonpay.com/integration-paths): session lifecycle, signed returns, webhooks, idempotency
- [Going live checklist](https://docs.vonpay.com/guides/go-live-checklist): production checklist

## Embedded Fields — in-page payment fields

- [Embedded Fields overview](https://docs.vonpay.com/embedded-fields): when to use Embedded Fields vs hosted; PCI implications
- [Customize the look & feel](https://docs.vonpay.com/embedded-fields/customize): interactive playground, three reference themes, the style allowlist, inner vs outer iframe
- [Elements reference](https://docs.vonpay.com/embedded-fields/elements): Card, Address, Email, Cardholder, Save-for-future-use, Payment-method-picker, Express Checkout (Apple Pay / Google Pay)
- [Custom checkout with Elements](https://docs.vonpay.com/embedded-fields/custom-checkout): discrete card fields via integrationMode:"elements" — mount the card element, submit() -> vp_pmt_*, charge server-side via /v1/payment_intents
- [Standalone Apple Pay & Google Pay](https://docs.vonpay.com/guides/standalone-wallets): the express-checkout element (recommended) OR bring-your-own-button (ApplePaySession / Google pay.js + POST /v1/public/wallets/{apple,google}-session + POST /v1/public/tokens instrument:wallet, which charges immediately)
- [Element events](https://docs.vonpay.com/embedded-fields/events): on/off(event, handler); 4 events ready/change/focus/blur with ElementChangeEvent {complete, error}; binder-agnostic; locale option accepted but English-only today
- [Using React](https://docs.vonpay.com/embedded-fields/react): `<VoraProvider>`, `useVora()`, imperative `elements.create()` for multi-element checkouts
- [Error handling](https://docs.vonpay.com/embedded-fields/errors): `FrameError` codes and recovery
- [3D Secure](https://docs.vonpay.com/embedded-fields/3ds): modal harmonization, `disable3dsModal` opt-out, `confirmPaymentIntent` + `handleAction`

## Integration

- [Create a session](https://docs.vonpay.com/integration/create-session): server-side `sessions.create({ amount, currency, ... })`
- [Redirect to checkout](https://docs.vonpay.com/integration/redirect-to-checkout): the hosted-redirect pattern
- [Handle the return](https://docs.vonpay.com/integration/handle-return): signed-return verification
- [Payment intents](https://docs.vonpay.com/integration/payment-intents): discrete-lifecycle API — capture, void, refunds, tokens (SDK 0.6.0+); MIT field (0.6.1+); `client_confirm` flow
- [Webhooks](https://docs.vonpay.com/integration/webhooks): event delivery, retries
- [Webhook verification](https://docs.vonpay.com/integration/webhook-verification): HMAC-SHA256 signing
- [AI agents](https://docs.vonpay.com/agents): MCP server integration for Claude / Cursor / Claude Code

## SDKs & Tools

- [Node SDK](https://docs.vonpay.com/sdks/node-sdk) — `@vonpay/checkout-node@0.11.0`: sessions, paymentIntents, capabilities, capture, void, refunds, tokens
- [Python SDK](https://docs.vonpay.com/sdks/python-sdk) — `vonpay-checkout==0.11.0`: same surface, snake_case
- [Browser SDK (Vora.js)](https://docs.vonpay.com/embedded-fields/quickstart): `https://js.vonpay.com/v1/vora.js` (currently v1.9.0, CDN-only — not on npm) — embedded fields, element library, capability gating. Complete the embedded flow with `vora.elements.create()` + `collection.submit()` (the deprecated single-field `card.tokenize()` refuses on single-embed binders with `frame_method_not_supported_for_session`).
- [CLI](https://docs.vonpay.com/sdks/cli) — `@vonpay/checkout-cli@0.5.1`: login, sessions, webhook trigger, health, doctor
- [MCP server](https://docs.vonpay.com/sdks/mcp) — `@vonpay/checkout-mcp@0.4.7`: tools for AI agents
- [REST API](https://docs.vonpay.com/sdks/rest-api): for languages without a first-party SDK

## API Reference

- [API reference](https://docs.vonpay.com/reference/api): endpoint-by-endpoint reference
- [Session object](https://docs.vonpay.com/reference/session-object): full schema
- [Error codes](https://docs.vonpay.com/reference/error-codes): typed `ErrorCode` union with merchant remediation
- [API keys](https://docs.vonpay.com/reference/api-keys): publishable (`vp_pk_*`) vs secret (`vp_sk_*`); test vs live
- [Security](https://docs.vonpay.com/reference/security): PCI scope, HMAC signing, idempotency
- [Versioning](https://docs.vonpay.com/reference/versioning): API + SDK semver policy
- [Test cards](https://docs.vonpay.com/reference/test-cards): success / decline / 3DS challenge cards
- [Rate limits](https://docs.vonpay.com/reference/rate-limits): per-endpoint ceilings
- [OpenAPI discovery](https://docs.vonpay.com/reference/discovery): `/openapi.yaml` + `/.well-known/openapi`

## Merchant obligations

Things Von Payments does NOT do — these are the merchant's responsibility:

- **Buyer receipt emails.** Von Payments does not email buyers a transactional receipt. Send your own from your `session.succeeded` webhook handler (or your post-redirect server route).
- **Recurring billing / subscription scheduling.** The `mit` block on `/v1/payment_intents` lets you charge a stored payment method (`recurring`, `unscheduled`, `installment`) using merchant-initiated transactions, but the scheduler, dunning logic, and subscriber portal are on you. You own the rebill loop — build per-cycle MIT charges yourself.
- **Dispute evidence submission.** `dispute.created`, `dispute.won`, and `dispute.lost` webhooks fire so you can track chargeback lifecycle. Submit dispute evidence via support.
- **Webhook-handler idempotency.** Dedupe on `sessionId` (or the event's `event_id`) — you may receive the same event more than once during retries.
- **Reconciliation when a signal is delayed.** If the signed return URL arrives but the webhook is delayed, treat the redirect as authoritative for fulfilment and call `GET /v1/sessions/{id}` to confirm. See [Reconciliation](https://docs.vonpay.com/integration/reconciliation).

## Optional

- [Sandbox testing guide](https://docs.vonpay.com/guides/sandbox)
- [Express Checkout Wallets](https://docs.vonpay.com/guides/express-checkout-wallets): activate Apple Pay & Google Pay — per-domain verification, who-does-what, troubleshooting
- [Platform sandbox](https://docs.vonpay.com/guides/platform-sandbox): for multi-merchant platforms / connected accounts
- [Troubleshooting](https://docs.vonpay.com/troubleshooting): common integration errors and fixes
- [Reconciliation](https://docs.vonpay.com/integration/reconciliation): redirect vs. webhook source-of-truth when one signal is delayed