PCI Vault Logo
Vault

The most straightforward use of the PCI Vault is tokenizing and decrypting card data directly to/from your own trusted servers.

Please note that the use of these basic endpoints provides very little benefit in terms of PCI compliance. For these endpoints to be usable, it means that the data is passing through your own server.

These endpoints are handy for development and troubleshooting, and for learning about PCI Vault. We recommend that you only access these endpoints through this documentation page or in your development environment for testing purposes.

To use PCI Vault without having payment card data going through your own servers, please use these endpoints:

POST /vault/ Encrypt and Tokenize Data
PCI DSS Scope: SAQ-EP

Encrypt, tokenize and store data securely in the vault.

The data object is limited to 256KB per request. It does not need to comply with the example value, but it must be a valid JSON object.

Please specify a number in the data with one of these keys: card_number, account_number, n, or number. Alternatively, specify a number in the query string.

(query)

The identifier for the key to use for encryption.

(query)

The passphrase for the key to use for encryption.

(query)

This number is used for generating a token. It is only required if not specified in the body, and will not be stored. If a number is submitted in both the body and this parameter, the number in the body will be used to generate the token.

(query)

A reference to assist with lookups in the vault. We recommend using a unique customer ID in this field.

(query)

The tokenization algorithm to use. See the tokenization guide for more information.

Any valid JSON object

POST
https://api.pcivault.io/v1/vault/
Response Code: 200 (example)
GET /vault/ Decrypt or List Tokenized Data
PCI DSS Scope: ROC

Get data from the vault. This endpoint will either decrypt your data, or list your tokens, depending on the input.

If the token, user, and passphrase is provided, the associated data will be decrypted and returned.

If the token and passphrase is omitted from the input, this endpoint will generate a list of tokens grouped by key in a tree-like structure. The tree will have the same structure as the example response below. In most cases, this list will be limited to only a few tokens. If there are more tokens than the limit allows, the included tokens are determined non-deterministically. To make the list deterministic, make the limit higher, or specify more filters.

(query)

The token for the data to be decrypted.

(query)

The reference by which data must be filtered. If a token has been stored with a reference, both the reference and the token must be supplied in order to decrypt the associated data.

(query)

The identifier for the key used to originally encrypt the data. This field can also be used as a filter for retrieving a tree.

(query)

The passphrase for the key used to originally encrypt the data. This is not required for retrieving a tree, but it is required for decryption.

(query)

Limit the number of cards in the tree. This limit 5000 by default. To remove the limit, specify a negative limit. Warning: Your browser might not be able to render too many cards, we recommend you set the limit fairly low when trying this endpoint out.

(query)

Filter for tokens stored after or on this timestamp. The timestamp must be in the format YYYY-MM-DDThh:mm:ssZ (e.g. 2022-09-01T00:00:00Z) in UTC time. Only to-the-second precision is supported.

This filter only works for tokens stored after this feature was implemented on 16 August 2022.

(query)

Filter for tokens stored before this timestamp. The timestamp must be in the format YYYY-MM-DDThh:mm:ssZ (e.g. 2022-09-01T00:00:00Z) in UTC time. Only to-the-second precision is supported.

This filter will also return tokens stored before this feature was implemented on 16 August 2022.

(query)

A comma seperated list of fields to mask in the response. In a masked field, all non-space characters will be replaced by an asterisk (*), except for the last 4 characters

(query)

A comma seperated list of rule ids to apply to returned data in order. This does not change stored data.

GET
https://api.pcivault.io/v1/vault/?limit=250
# No Body
Response Code: 200 (example)
DELETE /vault/ Delete a Token
PCI DSS Scope: SAQ-A/D

Delete data by token.

(query)

The identifier for the key used to encrypt the data to delete.

(query)

The token for the data to delete.

(query)

If a token has been stored with a reference, both the reference and the token must be supplied in order to delete the associated data.

DELETE
https://api.pcivault.io/v1/vault/
# No Body
Response Code: 200 (example)
POST /vault/update Update Encrypted Data
PCI DSS Scope: SAQ-EP

Update the data stored by an existing token. This endpoint is useful for keeping Stored Credential transaction metadata up-to-date.

The JSON object that is currently stored under the token will be merged with the supplied data. If the supplied data contains a key that is already in the existing data, the new data will override the old data. Only first-level keys will be updated this way, meaning that a new nested object will completely override an old nested object.

The item's stored_at attribute will be updated to the time at which the update happened.

The following keys will be ignored in the update: card_number, account_number, n, and number. If you would like to override the data in one of these keys, it is better to create a new token.

(query)

The token for the data to be updated.

(query)

The identifier for the key to use for encryption.

(query)

The passphrase for the key to use for encryption.

(query)

The reference under which the data has been stored.

(query)

A comma seperated list of rule ids to apply to the data in order. The rules are applied to the data after the specified JSON has been merged in.

Any valid JSON object

POST
https://api.pcivault.io/v1/vault/update
Response Code: 200 (example)