Skip to main content

How to collect payment details online

Build a secure and PCI-compliant checkout form to collect online payment details with a managed Piiano Vault


When you collect sensitive payment details, you must comply with the Payment Card Industry (PCI) Data Security Standard (DSS) standards. Most merchants require a significant effort to achieve this compliance. However, you can avoid this compliance challenge if you remove your system from PCI scope by storing the payment details elsewhere.

Piiano Vault provides a secure and compliant way to collect and store your online payment details. It helps minimize your PCI scope by ensuring sensitive payment details never reach your servers.

This tutorial shows you how to set up a secure checkout form that stores payment details in Piiano Vault. It uses the Piiano Vault TypeScript SDK to embed a custom Piiano Vault payment form in your website. Piiano Vault inserts an iframe into a placeholder on your website that collects and securely stores the payment details in Piiano Vault. This approach ensures that the payment details never reach your servers and they stay out of PCI scope.

This tutorial uses a sandbox environment in the managed version of Vault to show you how to securely store a customer's payment details. The process is essentially the same for an on-prem version of Vault.

What you learn

  • How to create a Piiano Vault API key to communicate with Piiano Vault.
  • How to create a collection in Piiano Vault to store online payment details.
  • How to set up your checkout form to use Piiano Javascript forms library from the Piiano Vault TypeScript SDK to store payment details.

You’re responsible for your compliance with all applicable laws, regulations, and network rules when saving a customer's payment details online. For instance, if you save a customer’s payment method for future use, you need their consent. You must also provide a way for your customers to remove their payment details from your system.

Step 1: Create Piiano Vault API key

A Piiano Vault API key is a unique identifier that enables you to write data from a client into Piiano Vault. This tutorial uses the key to store and tokenize payment details but can do the same for bank account numbers or other personally identifiable information (PII).

To create a key:

  1. Log in to your Piiano Vault account. You can sign up for a free sandbox environment if you don't have a Piiano Vault account.
  2. Navigate to your Vault dashboard.
  3. Open Identity and Access from the left navigation.
  4. On the Roles tab, select New role.
  5. Name the role PublicPciTokenizer, choose the CapTokensWriter capability and PolAllowTokenizePci policy.
  6. Select Create role.
  7. On the Users tab, select New user.
  8. Give the user a name (e.g., WebApplication) and choose the PublicPciTokenizer role. Make sure the user state is set to Enabled.
  9. Select Create user.
  10. For the WebApplication user, click the actions dropdown and select Regenerate API key. This action generates a new API key for the user. You can use this API key in the form to tokenize sensitive information.

Step 2: Create a Piiano Vault collection

A Piiano Vault collection is a container for storing sensitive information. In this case, you want a collection to store the payment details. Fortunately, Piiano Vault includes a predefined template for this type of collection.

To create your payment details collection:

  1. Select Collections from the left navigation and then New collection.
  2. Choose the Store payment cards template and select Create.
  3. Name the collection payment_details and make sure you have holder_name, number, expiration, and cvv properties.
  4. Select Create collection.

Step 4: Set up your checkout form to use Piiano Vault

You can now create your online payment form to store the payment details in the payment_details collection using a Piiano form and send a Vault global identifier for this information to your server-side endpoint /checkout. You can then use this Vault global identifier to process the payment details for this and future payments.

This is the code:

<!DOCTYPE html>


<meta charset="UTF-8">
* Include the Piiano Vault TypeScript SDK forms bundle.
<script src=""></script>

* Create an empty placeholder `div`. Piiano Vault inserts an iframe into this `div` that it used to post the payment transaction data to your payment_details collection on Piiano Vault.
<form id="payment-form" action="/checkout" method="POST" >
<h1>Payment details:</h1>
<!-- Display payment details form-->
<div id="payment-details">
<!-- Piiano Vault inserts the payment details form here -->
<input type="submit" value="Pay/Add card" />

* Add the API key you generated for your vault in your Piiano account.
const apiKey = '<WebApplication user API key>';
* Add your vault URL. This is the URL you see in your management console.
const vaultURL = "";
let protectedForm = null;

addEventListener('load', () => {
// (Optional) Style your embedded form.
const style = {
theme: "default",

protectedForm = pvault.createProtectedForm(document.getElementById('payment-details'), {
collection: "payment_details",
// Set up the styles for the form.
// Set up the fields for the form.
fields: [
{ name: "holder_name", label: "Card holder", value: "Jane Doe", dataTypeName: 'CC_HOLDER_NAME' },
{ name: "number", label: "Card number", value: "4111111111111111", dataTypeName: 'CC_NUMBER' },
{ name: "expiration", placeholder: "Card expiration", value: "12/25", dataTypeName: 'CC_EXPIRATION_STRING' },
{ name: "cvv", placeholder: "Card CVV", value: "123", dataTypeName: 'CC_CVV' }
hooks: {
onSubmit: console.log,
onError: console.error

* Set up the variables to collect the details from the form.
const form = document.querySelector('#payment-form');

* Listen for the form submission.
* Note that you’re preventing the default event behavior so the form doesn't automatically submit its content to /checkout.
form.addEventListener('submit', async (event) => {

* Collect the payment details token from Piiano Vault.
const paymentDetailsToken = await protectedForm.submit();

* Store the token Piiano Vault provided for the payment details in a hidden input field, add it to the form, and submit the form.
const hiddenInput = document.createElement('input');
hiddenInput.type = 'hidden'; = 'payment_details_token';
hiddenInput.value = paymentDetailsToken;


Your system now contains a payment details record containing a Vault global identifier, similar to this:

  "payment_details_identify": "pvlt:detokenize:payment_details::d27923c6-5d16-41e3-89ee-118b05a25372:"

Where d27923c6-5d16-41e3-89ee-118b05a25372 is the ID for a token that represents the details stored in the Vault payment-details collection, details similar to this:

  "holder_name": "Jane Doe",
"number": "4111111111111111",
"expiration": "12/25",
"cvv": "123"

You've created a form that collects sensitive payment details but keeps your business system out of scope for PCI compliance. You've done this by storing the payment details in Piiano Vault and a Vault global identifier for these details in your system.

You can now use this Vault global identifier to send a request to your payment gateway to charge the payment details whenever needed.


Piiano Vault is not a payment gateway. It's a secure and compliant way to collect sensitive information online. You need to use a payment gateway to process payments. Piiano Vault integrates with payment gateways using a supported payment gateway integration.

Learn more: