Skip to main content

Checkout

This is the hosted-redirect path. To keep the buyer on your domain instead, use Embedded Fields — a drop-in card iframe you brand your page around — or Elements to place card, email, address, cardholder, and the payment-method picker as separately-placed elements in your own layout. The card itself stays one combined secure field (number, expiry, and CVC together); you theme its font and color, not its internal layout. Hosted Checkout is the fastest to integrate; the on-domain paths trade a little setup for progressively more branding control.

The simplest integration path: your server creates a session, the buyer pays on a Von-Payments-hosted page, and they're redirected back with a signed status. No PCI scope, no payment form to build, no payment-method matrix to maintain.

New to Vonpay? Start with the Checkout quickstart. The pages below are the deep reference. To compare paths first, see Choose your integration.

Flow​

Your Server                      Von Payments                    Payment Processor
     |                                |                                |
     |-- POST /v1/sessions ---------->|                                |
     |   (amount, lineItems, successUrl)|-- creates session in DB        |
     |<-- { id, checkoutUrl } --------|                                |
     |                                |                                |
     |-- redirect buyer to ---------->|                                |
     |   checkoutUrl                  |-- renders checkout page        |
     |                                |-- buyer fills billing info     |
     |                                |-- buyer selects payment method |
     |                                |-- processes payment ---------->|
     |                                |<-- payment result -------------|
     |                                |                                |
     |<-- redirect buyer back --------|                                |
     |   ?status=succeeded&sig=xxx    |                                |
     |                                |                                |
     |-- verify signature             |                                |
     |-- show confirmation            |                                |

Session lifecycle​

Every payment goes through a checkout session with these statuses:

pending ──> processing ──> succeeded
                      └──> failed ──> succeeded   (on a successful retry)
pending ──> expired (after the session TTL; default 30 min)
StatusMeaning
pendingSession created, buyer hasn't started paying yet
processingBuyer is on the checkout page, payment form loaded
succeededPayment completed successfully
failedPayment was declined or failed
expiredSession TTL elapsed before buyer completed payment (default 30 min, configurable 5 min–7 days via expiresIn)

succeeded and expired are terminal. failed is not terminal — a session that failed an attempt can still converge to succeeded on a successful retry. (processing can also revert to pending.) Always treat the webhook / signed return as the source of truth for the final outcome.

What the buyer sees​

When the buyer arrives at the checkout URL, they see:

  1. Merchant header — your company name
  2. Order summary — line items, quantities, prices, total (from your session data)
  3. Billing address form — country, name, address, city, state, ZIP, phone
  4. Payment methods — automatically detected based on buyer's device and location:
    • Credit/debit cards (Visa, Mastercard, Amex, etc.)
    • Apple Pay (on Safari/iOS)
    • Google Pay (on Chrome/Android)
    • Klarna, Amazon Pay, and 130+ methods (based on merchant configuration)
  5. Pay button — submits the payment

Security​

  • PCI SAQ-A — Card data is entered in a secure iframe. It never touches Von Payments' servers or yours.
  • Encrypted PII — Buyer name and email are AES-256-GCM encrypted at rest.
  • Signed return URLs — The redirect back to your site includes an HMAC-SHA256 signature. Always verify it server-side.
  • Session tokens — The session ID ends in a 16-character random token (vp_cs_{test|live}_<16>). It cannot be guessed.
  • HTTPS return URLs — Merchant-supplied URLs (successUrl / cancelUrl) must use HTTPS (localhost exempt for test-mode keys). Live-mode keys reject loopback URLs.

Payment routing​

Von Payments runs a gateway-orchestration layer called VORA. When you call POST /v1/sessions, VORA selects the underlying payment processor based on the merchant's configuration, processor health, and routing rules — all server-side. The merchant API does not expose which processor handled the session; your integration is identical regardless of routing decisions.

See VORA — Payment Routing for the full concept.

What you don't need to do​

  • Build a payment form — we handle it
  • Handle PCI compliance — card data never touches your servers
  • Integrate individual payment methods — they're auto-detected and rendered
  • Manage 3D Secure — handled automatically when required
  • Build mobile-specific flows — the checkout page is responsive
  • Pick a payment processor — VORA routes for you

Next steps​