PCI Vault Logo
Hosted Forms

The most compliant way to capture payment card data from a user is to get it with a form that is not hosted by yourself, but by a PCI DSS compliant vendor like PCI Vault.

You can pull such a form into your own system or website by using an iframe or by opening the form in a separate browser window or tab.

These forms leverage PCI Vault's powerful capture endpoint technology. To get the tokenization result from the form input via webhook, make sure to specify a webhook URL endpoint on the capture endpoint when you generate it.

Standard Hosted Form

PCI Vault's hosted forms range from very simple to very powerful. The simplest way to use a hosted form is by using on of PCI Vault's standard hosted forms. This can be done in two steps:

  1. Generate a capture endpoint, making sure to keep the unique_id and secret around.
  2. Load the standard form using a link with the unique_id and secret. For example, to use our standard payment card data hosted form, you can use the link https://api.pcivault.io/v1/capture/iframe/pcd?unique_id=your_unique_id_here&secret=your_secret_here

This link can be used in the src attribute of an iframe, and it should work out of the box, as long as you have a valid unique id and secret.

PCI Vault currently has 2 standard forms available:

  1. For payment card data, please use https://api.pcivault.io/v1/capture/iframe/pcd
  2. For bank accounts, please use https://api.pcivault.io/v1/capture/iframe/ach

Configured Hosted From

PCI Vault also offers highly customisable forms, which you can use to generate a form with your own branding, or other customisation. When you generate such a form, it will have its own id and be publicly accessible. The process for creating and using such a form has three steps:

  1. Generate a capture endpoint, making sure to keep the unique_id and secret around.
  2. Create your customised hosted form, making sure to keep the returned id value around.
  3. Load the standard form using a link with the form id and the capture endpoint unique_id and secret. For example: https://api.pcivault.io/v1/capture/iframe/form_id_here?unique_id=your_unique_id_here&secret=your_secret_here

The customisation options are as follows:

Attribute Description
form_type Determine the type of form to be customized. Possible values are pcd for payment card data, or ach for bank details.
form_id Specify the ID the form should have. This ID must be unique on a system-wide level. If not specified, PCI Vault will generate one for you.
css_links [1] Specify externally hosted CSS to modify the form's appearance.
js_links Specify externally hosted JavaScript to modify the form's appearance and behavior.
embedded_css [1] Specify CSS to embed on the hosted form in a <style> attribute. CSS needs to be encoded with base64 when sent.
embedded_js Specify JavaScript to embed on the hosted form in a <script> attribute. JavaScript needs to be encoded with base64 when sent.
force_keypad Force the use of a keypad with randomized buttons.
show_card Turn off the sample credit card on the pcd form. By default the card will show, set this to false to hide the card,
disable_luhn Turn off validation on the form. This works on the pcd form only.
strip_spaces Removes spaces from the credit card number if set to true. This works on the pcd form only.
field_options [2] Hides fields or disables validation on them.
success_callback A Javascript function to call if the form has been submitted successfully. Must be encoded in base64 when sent.
error_callback A Javascript function to call if an error occurs on form submission. Must be encoded in base64 when sent.
  1. A note on CSS:
    PCI Vault forms contain HTML ids in most of the form elements. The default forms only use html classes to apply styles, meaning that any style applied to the id will override the default style. Styling the elements by id is the most reliable way to style the form according to your needs.
  2. Field Options:
    The field options must be a JSON object where the keys are the field names, and the values are themselves JSON objects with validate and visible as keys and true/false as values. Unspecified field names will be both visible and validated. If a field is specified without validate or visible in the object, the missing value be set to true unless visible is false, in which case validate will be false also.

When you access the form with the link, you also have the following options that you can specify in the query string:

  • testing will cause the form to submit to api-stage.pcivault.io instead of api.pcivault.io if set to true.
  • title will set the page title if the form is displayed in a browser window or tab.
  • Any other query string parameter will be added to an extra_data object, which will be submitted along with the form's data to PCI Vault.

Custom Hosted Form

PCI Vault can also host a custom form for you. This allows you to build a completely custom form using Javascript, but have the form be hosted by PCI Vault in our PCI DSS compliant environment.

To create a form like this, you can follow the same steps as in creating a Configured Hosted Form, except that you must use custom for the form type. You can put your Javascript in the embedded_js field, or you can host it externally and link it with the js_links field.

To render the form, your Javascript needs to add a function called custom_form to the DOM window object. This function can take in 2 arguments. The first argument will be a Javascript reference to a div element on which the form can be mounted. The second argument will be an object in this format:

    "submit_secret": "the_secret_specified_in_the_link_query",
    "submit_url": "/v1/capture/unique_id_here",
    "force_keypad": false,
    "show_card": true,
    "disable_luhn": false,
    "strip_spaces": false,
    "field_options": {},
    "extra_data": {},
    "testing": false

Take note that the submit_url will be always in the format /v1/capture/{unique_id}. Your Javascript routine will have to prepend "https://api.pcivault.io" or "https://api-stage.pcivault.io", depending on the testing flag being set to true or false respectively.

The code that calls the Javascript method looks like this:

window["custom_form"](document.getElementById("mount_form_element"), properties)

Using this option requires some development work, but it is also the most flexible. The form can be written in almost any front-end Javascript framework, as long as the framework gives you a way to add a function to the window object.