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.
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:
unique_id
and secret
around.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_hereThis 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:
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:
unique_id
and secret
around.id
value around.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_hereThe 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. |
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.extra_data
object,
which will be submitted along with the form's data to PCI Vault.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.