Session Object

A checkout session represents a single payment attempt from creation to completion.

Session ID

Format: vp_cs_{env}_{nanoid}

• vp_cs_test_k7x9m2n4p3q8r1s5 — sandbox session
• vp_cs_live_k7x9m2n4p3q8r1s5 — production session

The ID ends in a 16-character random string. It cannot be guessed.

Fields

Core fields

Field	Type	Always Present	Description
id	string	Yes	Session ID
status	string	Yes	Current status: pending, processing, succeeded, failed, expired
mode	string	Yes	Payment mode (payment)
merchantId	string	Yes	Merchant account that owns this session
amount	integer	Yes	Payment amount in minor units
currency	string	Yes	ISO 4217 currency code (a required 3-letter uppercase code)
country	string	No	ISO 3166-1 alpha-2 country code (optional)
description	string	No	Human-readable description of the payment (max 500 characters)
successUrl	string	No	Redirect URL on success — echoes the value supplied at creation (null if none)
cancelUrl	string	No	Redirect URL on cancel — echoes the value supplied at creation (null if none)
collectShipping	boolean	No	Whether to collect shipping address on checkout page
shippingAddress	object	No	Buyer's shipping address (only present when status is succeeded)
transactionId	string	No	Payment provider's transaction ID (set on completion)
metadata	object	No	Merchant-provided key-value pairs (passed through to webhooks)
createdAt	string	Yes	ISO 8601 creation timestamp
updatedAt	string	Yes	ISO 8601 last update timestamp
expiresAt	string	Yes	ISO 8601 expiry timestamp

Buyer and reusable tokens

Vaulting a reusable card-on-file token through the embedded charge-and-save flow requires a buyer on the session. With a buyer attached, submit() charges the card and returns a reusable vp_pmt_* token in one step. Guest / no-buyer sessions charge once and vault nothing — submit() resolves with a charge-only result (charged: true along with last4 and brand) and no token. Set the buyer when you create the session.

Payment routing (VORA)

Processor selection happens server-side inside Von Payments. The merchant API does not expose which processor was used — neither POST /v1/sessions nor GET /v1/sessions/:id returns processor identifiers. Your integration is identical regardless of which processor fires the charge. See VORA — Payment Routing for context.

Status Lifecycle

pending ──> processing ──> succeeded
                       └──> failed ──> succeeded   (retry converges)

pending ──> expired
processing ──> expired

Status	Description	Trigger
pending	Session created, waiting for buyer	POST /v1/sessions
processing	Buyer has acted; charge in flight	Buyer submits payment
succeeded	Payment completed	Payment processor confirms the capture
failed	Payment declined or errored	Payment processor rejects
expired	Session reached its expiry without completing	Cleanup sweep (see Rules)

Rules

• A succeeded session cannot become failed. The reverse, however, is allowed: a failed session that the buyer retries successfully converges to succeeded.
• A session can only be used once — no replays.
• Expired sessions cannot be re-activated — create a new session.
• Session TTL defaults to 30 minutes, but is configurable per session via expiresIn (from 5 minutes up to 7 days). expiresAt equals the creation time plus that TTL.
• A session that passes its expiresAt without completing is moved to expired by a periodic cleanup sweep (not at the exact instant the TTL elapses). Only sessions that have not moved money are expired this way.