Vault - for Storing Sensitive Data

Many automations run on Automation Cloud involve a card transaction. We have a secure process for transferring card data from your website or application to our infrastructure where we can then inject the correct details at the required time in the automation's lifecycle.

We call this system Vault. You will see that name referenced throughout our documentation.

You can also store sensitive data that isn't related to card data (we call this arbitrary data) using the same, secure system.

For both card and arbitrary data, capturing the data uses the same process:

You make an API call to request a One Time Password (OTP)
You present the user with an iFrame hosted on our infrastructure (using the OTP)
Your user inputs their sensitive data
We encrypt the data and return a token to the parent window for you to use later

TIP

This is the process for capturing the data. After this, you will want to use the token we have returned as an input for a job you are running on Automation Cloud. You can read more about inputs and outputs in the API reference:

Requesting a One Time Password (OTP)

An OTP is used in the exchange of sensitive (for example credit/debit card) data for a token. You need the OTP to securely load an IFrame for collecting user data.

POST/otp

curl -X post 'https://vault.automationcloud.net/otp'

Example Response:

{
    "id": "5a319910-4f4e-4f62-a8a5-a9d11d67d199",
    "object": "otp"
}

👆 Your OTP

The response contains the one-time password object. You need the id from this object to use in the card form query string. Please note that OTP expires in 1 hour if it's not used. Use this id as otp in next step

Save the PAN

To save a PAN you need the one-time password id from step 1 to authorise the request:

OTP (one-time password, usually UUID v4). PAN (payment card number, 15 or 16 digits). This PAN will be encrypted and stored in the Vault permanently. It is not possible to decrypt the PAN without the decryption key, which we never store.

The OTP and PAN would usually be supplied directly to our Vault from the payment form on your customer's browser. This is so you never handle the customer's PAN on your server.

POST/pan

export VAULT_API="https://vault.automationcloud.net"

curl -X POST "$VAULT_API/pan" \
  -d@-
  {
    "otp": "5a319910-4f4e-4f62-a8a5-a9d11d67d199",
    "pan": "4111111111111111"
  }

The result of this call must be stored in your database as the permanent ID of the user's payment card. It can not be used to retrieve or decrypt the card, it can only be used to issue a payment card replacement token for use in the Automation Cloud.

{
    "object": "decryption",
    "id": "401d406f-b39a-49b6-9c3f-4c0c820f4370",
    "key": "a23a64f4b14ae79ea7a26c440d9e4dac-132f73475acd8dd7dd8f7ec85d453c0a-998b41c0c207917351889f314026f670",
    "panToken": "3233a67212ebed7ee6ba953475a7c386-7252623476b566db29922dc88b3adc09-3a251ed802c15276636bf225b300591c:3ad64203bf93305eacab32f466e1120d-5795613f00e693ba299f243da757ac9b"
}

id: ID of PAN. Save this in your database. This ID is the only representation of user's payment card number. Later it will be used to issue a payment card replacement token. It can not be used to retrieve the original card number.
key: The PAN decryption key. This will be given to Automation Cloud along with the temporary card token and will be used during the automation.
panToken: This payment card replacement token should be used when you supply input data for your automation Job on the Automation Cloud. The token expires after some time (currently 1 hour) and a new token must be issued for each new job. The same token can't be used twice.

Embedding an iframe with the OTP

The URL you should use for embedding for your end user depends on whether you want to capture full payment information or arbitrary data.

Payment information should be captured using https://vault.automationcloud.net/forms/index.html

Arbitrary data should be captured using https://vault.automationcloud.net/forms/single-input.html

You must provide a valid OTP otherwise the input element won't be created. The basic iframe with vault's hosted form looks like:

<iframe
    src="https://vault.automationcloud.net/forms/single-input.html?otp=5a319910-4f4e-4f62-a8a5-a9d11d67d199"
></iframe>

Arbitrary Data Configuration Options

You can supply some of the options below as query params, such as setting validation rule or styling.

Key	Required	Default	Description
`otp`	`true`		One Time Password issued by vault
`css`			Supply your CSS URL. The form only accepts valid absolute url's.
`validateOnInput`			When `?validateOnInput=on` is supplied, it checks the validation of the field whenever the `input` event is emitted.
`inputType`		`text`	Set the type of input to `text` or `password`.
`pattern`			The validation rule following the `pattern`open in new window format.
`minlength`			The minimum length of the input - non integer values will be ignored.
`maxlength`			The maximum length of the input - non integer values will be ignored.
`required`		`false`	When `?required=true` the input will be mandatory.

For example:

import querystring from 'querystring';
const url = 'https://vault.automationcloud.net/forms/single-input.html';
const configs = {
    otp: '5a319910-4f4e-4f62-a8a5-a9d11d67d199',
    css: 'https://example.com/my-style.css',
    validateOnInput: 'on',
    inputType: 'password',
    pattern: '[a-z]',
    minlength: 4,
    maxlength: 8,
    required: true
};
const query = querystring.stringify(configs); // otp=5a319910-4f4e-4f62-a8a5-a9d11d67d199&....&required=true
const iframeSrc = url + '?' + query;
...
// set the url to your iframe
document.getElementById('#ac-iframe').setAttribute('src', iframeSrc);

Interacting with the Form

You can interact with the form by posting and listening using window.postMessage()open in new window.

Parent Window => Iframe

You can submit or validate the form by sending a message to the form. use IframeElement.contentWindow.postMessage(message-name, '*') (See the JSFiddleopen in new window).

Event	Description
`vault.submit`	Validate and submit the form.
`vault.validate`	Validate the form without submitting.

Iframe => Parent Window

The hosted form sends several kinds of messages to its parent window (your website). To receive these messages, you will need to add an event listener.

Event	Description
`vault.output`	Contains the `token` when the data is successfully saved in the vault. You can use this `token` for your automation.
`vault.validation`	Response to the `vault.validate` message. It returns `isValid: true
`vault.error`	Returns any error response from the vault.
`vault.validationError`	When the user submits the form but the validation has failed.
`vault.dimensions`	Dimensions of the form when `resize` event is emitted.

Using the returned Token as Job Input

export ACLOUD_API="https://api.automationcloud.net"
export SECRET_KEY="785aea134029bd077aaa67efb3c18086f24b69ec3a850717"
export JOB_ID="85f01a4b-1e31-4857-8393-ec8e50c16f06"

# vault.output's data from the form: { token: "22ea30bd-2a1f-47ac-820e-4be7db055b3d" }
export TOKEN="22ea30bd-2a1f-47ac-820e-4be7db055b3d"

curl -sS -X POST "$ACLOUD_API/jobs/$JOB_ID/inputs" \
  -u "$SECRET_KEY:" \
  -d@- <<EOF | jq
  {
    "key": "sensitiveInput",
    "data": {
      "\$token": "TOKEN"
    }
  }
EOF

PCI Compliance

Our infrastructure is PCI Level 1 certified by an external QSA. Using the payment forms we host significantly reduces the scope of compliance for PCI-DSS. This is because we host the payment form you include in your payment flow so you never touch any cardholder data.

WARNING

There's still an obligation on your part to comply with the security standard. To achieve this, and assuming using our hosted payment form is the extent of your interaction with cardholder data, your organisation should complete the reduced SAQ-A questionnaire from the PCI Security Standards Councilopen in new window.

TIP

If your organisation needs assistance completing SAQ-A in order to become PCI compliant, get in touch and we will happily introduce you to our Qualified Security Assessor.

# Vault - for Storing Sensitive Data

# Requesting a One Time Password (OTP)

# Example Response:

# Save the PAN

# Embedding an iframe with the OTP

# Interacting with the Form

# Parent Window => Iframe

# Iframe => Parent Window

# Using the returned Token as Job Input

# PCI Compliance