Tokens
Network tokens and payment instrument tokens — store and manage tokenized card credentials.
A token represents a network-tokenized card credential issued by the card scheme (Visa VTS or
Mastercard MDES) on behalf of a stored payment method. VINR creates and maintains tokens
automatically — you reference the parent pm_ ID on payments and VINR silently routes through the
live network token, improving authorization rates and keeping card data current via the card
network's account updater service.
Illustrative content. Hand-authored to demonstrate the Standard/Advanced pattern; the production page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.
The token objectAsk
idstringUnique identifier for the token, e.g. tok_5Xm1.
typeenumHow the token was issued. network_token — provisioned by Visa VTS or Mastercard MDES.
card_token — a VINR-managed instrument token for card-present or recurring use without a
full network scheme token.
paymentMethodIdstringThe pm_ ID of the payment method this token was created from.
networkTokenobjectPresent when type is network_token. Contains the live token detail returned by the card
network.
statusenumVINR-level token status: active, inactive, or expired. Reflects networkToken.status
but is also set to inactive when you call the deactivate endpoint directly.
createdAtintegerUnix timestamp when the token was created.
updatedAtintegerUnix timestamp when the token was last modified.
The network token objectAsk
VINR automatically provisions a network token with Visa VTS or Mastercard MDES whenever a card is
stored with a recurring or card_present usage intent. Merchants do not call a create
endpoint — the token is a side effect of creating or updating a payment method. Once provisioned,
VINR transparently uses the network token on every payment that references the parent pm_ ID,
passing the cryptogram required by the scheme. You can inspect the resulting token objects via the
endpoints below, and deactivate them when a card is lost or the customer requests removal.
Retrieve a tokenAsk
Fetch a single token by its tok_ ID.
List tokens for a payment methodAsk
Returns all tokens provisioned for a given payment method. Use the status query parameter to
filter to only active tokens.
| Parameter | Type | Description |
|---|---|---|
status | enum | Filter by token status: active, inactive, or expired. |
limit | integer | Number of results to return. Default 10, max 100. |
starting_after | string | Cursor for forward pagination — the tok_ ID of the last item from the previous page. |
Deactivate a tokenAsk
Deactivates a network token so it can no longer be used to authorize payments. Use this when a card
is reported lost or stolen, or when a customer requests that their credentials be removed. Deactivating
a token does not delete the parent payment method — the pm_ object is retained and you may
re-provision a replacement token by updating the payment method's usage intent. To fully remove the
instrument, detach the payment method separately.
Token eventsAsk
| Event | Fired when |
|---|---|
payment_method.updated | A network token is refreshed by the card network (account updater). The parent payment method's updatedAt is bumped and the token's lastRefreshedAt is updated. |
token.deactivated | A token transitions to inactive, either via the deactivate endpoint or a scheme-side revocation. |
Subscribe to these events via Webhook endpoints to keep your records synchronized without polling.
Next stepsAsk
- Tokenization overview — how VINR uses network tokens to raise authorization rates and keep card credentials current.
- Payment methods — create and manage the
pm_objects that tokens are attached to. - Payments — charge a stored payment method; VINR routes through the network token transparently.
