Payments Vault
Build your own checkout on the Vrio API without taking card data into scope. The Payments Vault SDK collects the card in Vrio-hosted fields and returns a single-use token you send to the API in place of a card number.
The Payments Vault lets you build your own checkout on the Vrio API while the card is collected inside our PCI Level 1 environment. You keep control of the page and the customer experience, without your systems ever handling a card number.
What is it
It's a JavaScript SDK that puts Vrio-hosted card fields onto your own checkout page. To the customer it looks like any other form: they type their card number, expiration and security code, and press your pay button. Behind the scenes, each of those inputs belongs to Vrio rather than to your site.
When the customer submits, the SDK trades the card for a single-use payment token — a short string like tok_use2_aB3dEf7hJk9mNp2qRs4tUv6w. That token goes to the Vrio API in place of a card number, and Vrio charges the card.
If you've used a hosted fields SDK before, this will feel familiar. The card is collected by us, but the checkout is still yours.
Why use it
Building your own checkout on the Vrio API normally means the card number is typed into your page and posted from your servers. That puts your business squarely in scope for PCI DSS — potentially several hundred security controls covering how card data is stored, transmitted and monitored.
That's a recurring cost rather than a one-off: security software and infrastructure to buy and maintain, external auditors to engage, an annual assessment to pass, and engineering time to keep it all in place as your systems change. Scope also spreads — every system the card number touches comes with it.
Most businesses would rather not take that on. The Payments Vault lets you keep the API integration and hand off the card handling: card details go from the customer's browser straight into Vrio's PCI Level 1 environment, and your systems only ever see a token.
- The card never reaches your systems — not your servers, and not even your page, which substantially reduces your PCI obligations compared with posting card fields yourself. PCI compliance is a shared responsibility, so confirm what applies to your business with your QSA.
- What you do get back is safe to keep — the last four digits, card brand and expiration aren't sensitive card data, so you can store and display them freely.
- You keep your checkout — your layout, your branding, your validation, your button. Only the card inputs are ours.
- Nothing on your page can read the card — tag managers, analytics, session recorders and anything else injected into your checkout can't reach into a field they don't own.
- It's still just an order — the token only changes how the card is collected, not what Vrio does with it. Payment routing, merchant selection, fraud rules, subscriptions, upsells and refunds all behave exactly as they do for any other order.
How a payment flows
- Your page loads the SDK and asks it to render card fields into containers you provide.
- The customer enters their card. Everything they type stays inside Vrio's fields — your page never sees it.
- You call
tokenize()when they submit. The card goes straight from the browser to the Payments Vault, and you get back a payment token plus safe display details like the last four digits and the card brand. - The token goes to whatever creates your orders — your own backend, or the browser calling the Vrio API directly. The Vault works the same either way.
- The order is created through the Vrio API, passing the token in place of card fields. Vrio redeems it and charges the card.
From step 5 onward there's nothing unusual about the order. It has a stored card, so upsells and recurring cycles bill against it normally.
Learn more: Integrating the Payments Vault →
What you'll need
A public key. Vrio issues you a key that looks like pk_live_…. It's safe to put in your page — it's designed to be public, and it can't be used to retrieve card data.
Your checkout domain registered against that key. The Vault only answers requests from domains you've registered, so anyone who copies your key can't use it from their own site. Registration is an exact host match with no wildcards, which means example.com, www.example.com and checkout.example.com are three separate entries. If you use per-branch preview domains, register each one.
Your usual Vrio API key for the call that creates the order.
Working with the token
The token is the one part of this flow that behaves differently from a card number, and it's worth understanding before you build.
It can only be used once
The token is destroyed the moment it's redeemed. There's no way to charge it twice, which is what makes it safe to pass around — but it also means a failed order can't be retried with the same token. To retry, the customer re-enters their card and you create a fresh one.
Tokens also expire on their own 15 minutes after they're created, so create one when the customer submits rather than holding one open while they browse.
Clear the token from your form on page load
Browsers restore hidden input values on reload and on back/forward navigation. If a spent token is still sitting in your form when the customer retries, the retry fails for a reason that looks nothing like the real cause.
Supported card brands
Charging a token works for Visa, Mastercard, Discover and American Express.
The SDK will happily tokenize Diners, JCB and UnionPay, but the charge then fails. If your business accepts those brands elsewhere, catch them at the checkout while the customer is still typing — the SDK tells you the brand as soon as it recognizes the number.
See how: Payments Vault Examples →
Related Documentation
- Integrating the Payments Vault — Load the SDK, render the fields, and charge the token
- Styling the Card Fields — Make the hosted fields match your checkout
- Payments Vault Examples — A complete, runnable tokenization page
- Payment APIs Overview — All the ways to process a payment with Vrio
- Checkout Settings — Vrio's fully hosted checkout page
Updated about 1 hour ago