Checkout
This is the hosted-redirect path: your server creates a session, the buyer pays on a Von-Payments-hosted page, and they're redirected back with a signed status. To keep the buyer on your domain instead, use Embedded Fields — the drop-in card iframe, or Elements to place each piece in your own layout.
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)
| Status | Meaning |
|---|---|
pending | Session created, buyer hasn't started paying yet |
processing | Buyer has acted — the payment form is loaded or a charge is already in flight (wallet taps flip to processing before the charge is sent). Not safe to treat as "not paying yet" — see Session object |
succeeded | Payment completed successfully |
failed | Payment was declined or failed |
expired | Session 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 on the server — a session that failed an attempt can still converge to succeeded on a successful retry.
confirmReturn treats failed and expired as final for the redirect decision only. Do not mark the order dead on a failed return — keep listening for charge.succeeded, or a buyer who retried successfully has paid you and is never fulfilled. To cancel the order, first close the session: a 200 means no payment can still land. The webhook is the source of truth; the signed return proves the message is authentic, never that money moved.
What the buyer sees
When the buyer arrives at the checkout URL, they see:
- Merchant header — your company name
- Order summary — line items, quantities, prices, total (from your session data)
- Billing address form — country, name, address, city, state, ZIP, phone
- 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)
- Pay button — submits the payment
Security
Card data is entered in a secure iframe and never touches your servers (PCI SAQ-A). successUrl / cancelUrl must be HTTPS (localhost exempt on test keys; live keys reject loopback). The redirect back carries an HMAC-SHA256 signature — proof the message is authentic, not proof of payment; read the outcome from the webhook or sessions.get. Processor selection is server-side and never exposed (VORA); 3-D Secure is handled on the hosted page. Full detail: Security.
Next steps
- Create a session — request shape, response shape, code samples
- Redirect to checkout — what to send the buyer
- Handle the return — verifying the signed redirect
- Webhooks — server-to-server confirmation