- Guides
- Proxy Recipes
- API
- Form JS
- External Links
The Basic endpoints provide the simplest way to tokenize and retrieve payment card data directly between your trusted servers and PCI Vault. They are ideal for getting started with the API, exploring its capabilities, and integrating PCI Vault into your development environment.
It's important to note that these endpoints offer limited PCI DSS scope reduction because the payment card data passes through your own infrastructure before being sent to PCI Vault. As a result, your systems may still be considered in scope for PCI DSS compliance.
These endpoints are primarily intended for development, testing, troubleshooting, and learning how PCI Vault works. For production environments, we strongly recommend using one of our secure capture or proxy solutions, which allow sensitive payment data to bypass your servers entirely, helping to significantly reduce your PCI DSS scope.
To integrate PCI Vault without payment card data ever passing through your own infrastructure, we recommend using the following endpoints:
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 support@pcivault.io.
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