- Guides
- Proxy Recipes
- API
- Form JS
- External Links
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:
- Allowing third parties to submit payment card data on your behalf; this includes getting data from your own website or app.
- Allowing third parties to access your payment card data.
- Sending data to third parties (like PSPs) directly from the vault.
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.
The identifier for the key to use for encryption.
The passphrase for the key to use for encryption.
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.
A reference to assist with lookups in the vault. We recommend using a unique customer ID in this field.
The tokenization algorithm to use. See the tokenization guide for more information.
Whether the returned data should include card metadata. When set to true, the BIN is queried and the issuer data is returned together with the token.
Any valid JSON object
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.
The limited results can be paginated
by means of the next_token query parameter. If the result is limited (by default only a maximum of 1024 tokens will be returned per page), this method will have a response header X-PCIVault-Next-Token containing a token which can be passed in the next_token query parameter to fetch the following page of results.
Note:
By default the fields containing sensitive data will be masked with *,
if you would like to receive the full unmasked data
from this endpoint contact [email protected].
The token for the data to be decrypted.
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.
Filter for tokens where the reference begins with the specified value.
The identifier for the key used to originally encrypt the data. This field can also be used as a filter for retrieving a tree.
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.
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.
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.
A comma separated 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
A comma separated list of rule ids to apply to returned data in order. This does not change stored data.
If set to true, decrypt all tokens in the tree. Note: every token in the tree will be decrypted and counted as an API operation, so use this with caution when using a large limit parameter.
Limit the number of cards in the tree. This limit is 1024 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. Depending on how many cards are in the vault, removing the limit might also result in an error due to a timeout.
The token received in the X-PCIVault-Next-Token header in a previous request.
Whether the returned data should include card metadata. When set to true, the BIN is queried and the issuer data is returned together with the decrypted data. Only applicable when decrypting data.
# No Body
Delete data by token.
The identifier for the key used to encrypt the data to delete.
The token for the data to delete.
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.
# No Body
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.
The token for the data to be updated.
The identifier for the key to use for encryption.
The passphrase for the key to use for encryption.
The reference under which the data has been stored.
A comma separated 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
When data is encrypted or decrypted, we store related metadata. This metadata can be thought of as a log of actions. Various parameters are captured for each log entry, things like IP address, user agent and type of action.
The results are returned newest to oldest.
The limited results can be paginated
by means of the next_token query parameter. If the result is limited (by default only a maximum of 1024 tokens will be returned per page), this method will have a response header X-PCIVault-Next-Token containing a token which can be passed in the next_token query parameter to fetch the following page of results.
The identifier for the key used to originally encrypt the data.
The token for the data.
The reference for the data. If a token has been stored with a reference, both the reference and the token must be supplied in order to locate the associated metadata.
Limit the number of metadata entries returned. This limit is 1024 by default.
The token received in the X-PCIVault-Next-Token header in a previous request.
# No Body