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 sessionvp_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 |
clientSecret | string | null | No | This session's client secret, the same value the create returned. Give it to the one page that renders this checkout, which passes it to vora.sessions.retrieve(). Absent or null when the session has none: the page then passes the session id. Returned by GET /v1/sessions/{sessionId} only, never by PATCH or expire. A secret: never log it or put it in a URL. |
status | string: pending | processing | succeeded | failed | expired | Yes | Where the session is in its lifecycle. The status table below gives the trigger for each value. |
expiredFrom | string | null: pending | processing | failed | authentication_cancelled | No | How an expired session expired, and whether a payment may still exist on it. null whenever status is not expired. pending means no payment had been started through Von Payments' servers, so nothing was charged. failed means nothing was charged either: a declined elements + chargeAtSubmit session that was closed with nothing recorded, or a session whose time limit passed while the buyer was at their bank's security check, once the payment provider confirmed that payment was never authorized. processing means a payment HAD been started and its outcome was never reported before the time limit passed: do not read it as "nothing was charged". On an elements + chargeAtSubmit session it can later change to failed when the provider confirms no authorization after the bank check times out; that attempt's payment_intent.failed / charge.failed webhooks announce it. Otherwise do NOT rely on polling the session or on a webhook to settle it, because a payment that lands on an already-expired session is not reported today. Contact support with the session id before charging the buyer again for the same order. null on a session that IS expired is unknown, and should be treated like processing. |
paymentStatus | string: unpaid | held | paid | cancelled | Yes | Did the money move? Deliberately separate from status, which says whether the buyer finished. unpaid means nothing is committed. held means authorized, not captured: the card is on hold and you must capture or void it. Do not fulfill on held. An authorization you never capture lapses at the issuer and the sale is lost, and the window is shorter than most integrations assume: around seven days on Mastercard, American Express and Discover, about five on a Visa merchant-initiated payment, as little as two for card-present. Treat the shortest as your deadline unless you know the brand. paid means captured, and is the one to fulfill on. cancelled means a hold released without ever being captured. Refunds are not reported here: a captured-then-refunded session stays paid, so read the refund for that. |
mode | string: payment | setup | Yes | Payment mode. |
captureMethod | string: automatic | manual | Yes | Echoes the captureMethod the session was created with (automatic or manual), so you can see which semantics it carries without inferring them from paymentStatus. |
integrationMode | string: embed | elements | Yes | The integration mode the session was created with, as applied: embed if you asked for elements and your account does not support it. The same value the create response returned. |
channel | string | null: virtual_terminal | subscription_card_update | Yes | Which Von Payments product created the session: virtual_terminal for a sale keyed in your dashboard's virtual terminal, subscription_card_update for a session Von Payments opened for a subscriber to replace their card, null for a session your integration created. Set by Von Payments; you cannot send it. |
chargeAtSubmit | boolean | Yes | Whether the embedded fields charge the buyer on submit, as applied at create: false unless the session is an elements session in payment mode that asked for it. |
threeDSecure | object | Yes | How the session will authenticate the cardholder if the bank asks for it: an object whose mode is in_page, redirect or not_applicable (treat it as an open list). Worked out each time you read it, so it follows your account's current setup. It says what will happen, not that a challenge ran. |
storedCredentialUse | string | null: recurring | installment | unscheduled | Yes | The storedCredentialUse declaration recorded on the session: recurring, installment or unscheduled. You set it at create, or later as unscheduled when you name a guest. null means none was declared. Read it back to confirm your declaration landed. |
setupForFutureUse | string | null: on_session | Yes | on_session when you declared setupForFutureUse at create or when you named a guest, otherwise null. This is your declaration. What a saved card actually records is on the charge or save result, where a buyer who ticked "save my card" (off_session) wins. |
savedPaymentMethodOptions | object | Yes | { paymentMethodRedisplay }: "enabled" when the session was created with savedPaymentMethodOptions.paymentMethodRedisplay: "enabled", so the embedded card form may list this customer's saved cards; otherwise "disabled". |
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 | null | No | ISO 3166-1 alpha-2 country code (optional) |
description | string | null | No | Human-readable description of the payment (max 500 characters) |
locale | string | null | Yes | The checkout page language you sent at create, as stored. null when none was sent. |
successUrl | string | null | No | Redirect URL on success. Echoes the value supplied at creation (null if none) |
cancelUrl | string | null | No | Redirect URL on cancel. Echoes the value supplied at creation (null if none) |
shipping | string: none | auto | required | Yes | Shipping-address collection mode actually applied: none, auto or required. Not necessarily what you sent: omit the field on create and this is your account setting (none out of the box). See Asking the buyer for more than a card. |
billingAddress | string: none | auto | required | Yes | Billing-address collection mode actually applied: none, auto or required. Your account setting when you omitted it. This is the mode, not the buyer's address. |
phone | string: none | auto | required | Yes | Phone collection mode actually applied: none, auto or required. The number the buyer typed is buyerPhone. |
collectEmail | boolean | Yes | Whether the checkout shows an email input even when a buyer email was pre-filled, as stored at create. |
nameCollection | string: none | auto | required | Yes | Whether this session requires the buyer's name: none, auto or required, from your account's buyer-field settings when the session was created. |
emailCollection | string: auto | required | Yes | Whether this session requires the buyer's email: auto or required, from your account's buyer-field settings when the session was created. Email is always collected, so it is never none. |
shippingAddress | object | null | No | Buyer's shipping address (only present when status is succeeded) |
buyerId | string (≤ 200) | null | Yes | Your own reference for this session's buyer, as sent at create, or set once later with PATCH. null when the session has none. The buyer's email and name are personal data and are never returned here. |
vp_buyer_id | string | null | Yes | The buyer Von Payments created for this session (vp_by_*), when the session named no buyer and a card saved here for charges made while the buyer is away belongs to it. Read it with GET /v1/buyers/{id}. null otherwise, including when you named the buyer with buyerId, or when the buyer's email identified one for a card saved without a payment (a card saved by a payment on a session without buyerId always goes to the buyer created for the session). Returned by GET only: the PATCH and expire responses always carry null. |
buyerPhone | string | null | Yes | The phone number the buyer typed on the checkout page. null when none was collected. Not the same as phone, the collection mode you set at creation, which decides whether the field is shown. |
transactionId | string | null | No | The payment provider's reference for this session's payment, set on completion. Not the id refunds take: use vp_tx_id. It names only a payment that went through: on a failed session it is null. When the latest declined attempt was recorded as a payment intent, last_payment_error.payment_intent_id names it. |
vp_tx_id | string | null | Yes | The Von transaction id (vp_tx_*): the id POST /v1/refunds takes as transaction, and the same vp_tx_id the charge.* webhooks carry, so a server that confirms a payment by reading the session can refund it without a webhook. null until captured, and while paymentStatus is held. Can trail paid by a few moments: read again rather than treating null as "no payment". Also null when vp_tx_count is 2 or more. |
vp_tx_count | integer | Yes | How many separate payments are recorded for this session: 0 before payment and while held, 1 normally. 2 or more means the buyer was charged more than once: vp_tx_id is then null on purpose. Check the payments by hand before refunding or fulfilling. |
amount_refunded | integer | null | Yes | Total refunded so far on the session's payment, in minor units: refunds done or still in progress (requested). Failed and canceled refunds are not counted. On GET only; PATCH and expire return null. Also null when vp_tx_id is null or the totals could not be read at that moment. To list the refunds themselves, call GET /v1/refunds?transaction= with vp_tx_id. |
remaining_refundable | integer | null | Yes | What a refund with no amount would return now, in minor units: the captured amount minus amount_refunded. A refund still in progress is already subtracted; if it later fails, its amount comes back. 0 whenever refundable is false. null in the same cases as amount_refunded. |
refundable | boolean | null | Yes | Whether the payment qualifies for a refund now, by the same rules POST /v1/refunds applies: false when it is not settled yet, disputed, already fully refunded or not refundable through the API. Account conditions, such as refunds being switched on for your payment provider, are still checked by the refund call. null in the same cases as amount_refunded. |
paymentIntentId | string | null | Yes | The payment intent this session's payment created. On a captureMethod: "manual" session this is the id you capture or void once paymentStatus reads held. Also set on a paid automatic payment, where the money is already taken: use it to read or refund, never to capture. Decide from paymentStatus (only held owes a capture), not from this field being present. null before payment, for a few moments while a payment is confirmed, and when more than one payment intent is recorded (check by hand rather than capturing either). A declined attempt is not this session's payment: on a failed session it is null. When the declined attempt was recorded as a payment intent, last_payment_error.payment_intent_id names it. |
paymentMethod | string | null | Yes | On an integrationMode: "elements" session with chargeAtSubmit: false, the card the shopper saved (vp_pmt_*), the newest one if they saved more than one. The session status does not change on such a save, so read this field rather than waiting for succeeded. Reported for 30 days after the save, on GET only. Otherwise null. |
payment_method_card_check | object | No | Whether an approved $0 card check stored paymentMethod: { status: "approved", stored_credential_use }, the same object as card_check on GET /v1/payment_methods. Its stored_credential_use is what the check declared; a later save of the same card does not change it. null when the card was saved without one. Absent when paymentMethod is null, and from a PATCH or expire response: absent means not read, never no check. |
retry | object | null | Yes | Whether a declined session whose card form is on your own page (an elements or embed session; the hosted checkout page has its own retry) will take another card, on an account with retry on the same session switched on: { allowed, attempts_remaining }. allowed: true means a decline re-opened the session (status is pending) and the buyer can pay with another card. allowed: false with attempts_remaining above 0 means re-opened, with the next card form still being prepared: read again in a second. allowed: false with attempts_remaining: 0 means the session ended with a decline (failed). null when retry on the same session is not switched on for your account, the session's card form is not on your own page, nothing has been declined, or a decline handed the session back (pending) without using up an attempt, in which case it can still be paid. Only allowed: false with attempts_remaining: 0 is final; close the session before you cancel an order on it. This is the only place to learn it after a decline on the bank's 3-D Secure page, where no charge response is waiting. The failure webhooks carry the same field. |
retry_after_ms | integer | null | Yes | A hint that this answer is about to change: read the session again after this many milliseconds. Set while a declined session's new card form is being prepared and while a payment is still being settled (outcome: "in_flight"); null when nothing is expected to change on its own. It grows as the state ages. It is a hint, not a promise: keep your own limit on how long and how often you read. |
outcome | string | null: open | reopened | in_flight | declined | authorized | charged_once | closed_no_charge | needs_review | Yes | Advisory. One word for where this session stands for money, worked out only from the other fields of this response: open, reopened, in_flight, declined, authorized, charged_once, closed_no_charge or needs_review (null on a card-saving session). Use it as a second opinion: act only when your own reading of status, paymentStatus, vp_tx_count and expiredFrom agrees, and have a person look when it says needs_review or disagrees with you. open and reopened mean no payment is recorded, not that none can arrive. A charge you make with POST /v1/payment_intents is never reflected here. |
last_payment_error | object | null | Yes | The most recent declined attempt, when the session failed, was re-opened after a decline, or is expired with expiredFrom: "failed": { payment_intent_id, code, decline_code, action, buyer_message, buyer_action }. payment_intent_id is the payment intent (vpi_*) of that declined attempt: pass it to GET /v1/payment_intents/{id} to read the attempt in full. After more than one try it is the latest declined attempt. It is not paymentIntentId, which names only a payment that recorded money and stays null when every attempt was declined. code is card_declined (the bank refused) or payment_failed (any other reason); decline_code uses the same values as a payment intent's decline_code, or null; action maps it the same way as a payment intent's action. These three are for your server only: action reads hard for a card the bank flagged or a refusal by your own rule, which tells a card tester which is which. On the shopper's page show buyer_message (English wording, already safe to show as plain text: flagged cards and your own rules read as an ordinary decline, and a wrong card number, security code, postal code or expiry date reads as one "check your card details" message) and buyer_action (the matching advice). Filled in on GET. PATCH and expire fill it in only on the answers that read the session's payments again (a PATCH that changes nothing, and the answer that closes a payment waiting on the bank's security check); their other answers return null. Also null if it could not be read at that moment, which never fails the read. |
card_form_group | string | null | Yes | The card_form_group set at create or with PATCH (write-once), otherwise null. Returned on the secret-key read only, never to the browser. |
metadata | object of string | null | No | Your key-value pairs from POST /v1/sessions, plus any merged in later with PATCH /v1/sessions/{id}. Keys reserved by Von Payments are never in it. Not included in webhook payloads: read the session to get them. |
createdAt | string | Yes | ISO 8601 creation timestamp |
updatedAt | string | Yes | ISO 8601 last update timestamp |
expiresAt | string | Yes | ISO 8601 expiry timestamp |
A buyer on the session, with the buyer's agreement, is what lets the embedded fields save a reusable vp_pmt_* alongside the charge. In embed mode a session with neither a buyerId nor a buyer email charges once and saves nothing (charged: true, no token), and from vora.js 1.44.0 the agreement must be known when the form loads. When the session has no buyerId and the card is saved (the buyer agreed through the save box or your page's wording, or, with a buyer email, you declared on_session), Von Payments creates a buyer for the session and saves the card to it, in elements mode with or without a buyer email and in embed mode when the session carries an email; vp_buyer_id names that buyer. An email never files the card under an existing buyer that has the same email. The embed lists a returning buyer's cards saved in prior completed sessions only when you opt in (details).
Payment routing (VORA)
Processor selection happens server-side. Neither POST /v1/sessions nor GET /v1/sessions/:id tells you which processor runs the payment — VORA.
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, and cannot be charged again: one session pays for one order once. The reverse is allowed.
failedis not terminal; a buyer whose card was declined may pay again on the same session until it expires, and a successful retry converges it tosucceeded. Do not mark an order dead onfailed. Keep listening forcharge.succeeded. - 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).expiresAtequals the creation time plus that TTL. - A session that passes its
expiresAtwithout completing is moved toexpiredby a periodic cleanup sweep (not at the exact instant the TTL elapses). Only sessions that have not moved money are expired this way.