Tokens

POST /v1/tokens creates a reusable payment-method token. Token IDs use the vp_pmt_test_* / vp_pmt_live_* prefix.

This is the server-side token endpoint. For the browser/embedded flow — where the Embedded Fields SDK (vora.js) mints a token from card fields the buyer types — see Tokenization.

Required key: secret key (vp_sk_*). Available in SDK 0.11.0.

Create a token

curl https://checkout.vonpay.com/v1/tokens \
  -H "Authorization: Bearer vp_sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "buyer_id": "buyer_abc", "provider_reference": "pm_token_abc123" }'

const token = await client.tokens.create({
  buyerId: "buyer_abc",
  providerReference: "pm_token_abc123",
});

Request — CreateTokenRequest

All fields are optional, and the schema is strict (unknown fields are rejected).

Field	Type	Required	Description
buyer_id	string	—	Buyer to associate the token with (enables reuse / MIT).
provider_reference	string	—	A gateway-specific reference for the payment method — depending on the underlying gateway, an iframe-vault payment-method handle or a server-side setup reference. Required for live tokenization (see below); ignored in sandbox. Max 255 chars.
card_last4	string	—	Last four digits, for display.
card_brand	string	—	Card network — one of visa, mastercard, amex, discover, unionpay, jcb, diners, unknown.
exp_month	integer	—	1–12.
exp_year	integer	—	Four-digit year (≥ current year).
metadata	object	—	Record with string keys and arbitrary JSON values (size-capped, scrubbed).
setup_for_future_use	string	—	off_session or on_session.

Sandbox vs. live:

• Sandbox keys auto-mint a mock card token when no card data is supplied — useful for SDK examples. provider_reference is ignored.
• Live keys require a provider_reference (the payment method must already exist at the gateway). Without it, the request returns 400 validation_error.

Response — PaymentMethodToken

{
  "id": "vp_pmt_test_QAqnXEJF_TCum1jg",
  "status": "active",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2030
  }
}

Field	Type	Description
id	string	Token ID (vp_pmt_test_* / vp_pmt_live_*).
status	string	active or revoked.
card.brand	string	Card network (e.g. visa).
card.last4	string	Last four digits.
card.exp_month	integer	1–12.
card.exp_year	integer	Four-digit year.

Status

Status	Meaning
active	The token can be used to create a payment intent.
revoked	The token has been revoked and can no longer be used.

A token does not carry a separate expired status. Card expiry (exp_month / exp_year) is stored on the token's card object, but the token itself stays active until it is revoked.

Errors

Status	Code	Cause
400	validation_error	A live key was used without provider_reference (or another invalid request field).
501	endpoint_not_implemented	The merchant's gateway does not expose tokenization through this endpoint — some gateways accept only browser-minted handles and bypass /v1/tokens entirely.

Using a token

Pass a token's id as the payment_method when creating a payment intent. See Payment Intents.

Related

• Tokenization — minting tokens browser-side with the Embedded Fields SDK
• Payment Intents — charging a token
• Test Cards — sandbox token shapes