Records and Aliases

Learn about the concept of records, aliases and fields.

Introduction

Alias and Record are both non-sensitive information to refer to the sensitive values stored in the Vault.

  • An Alias is the non-sensitive value that corresponds to a single field stored in the vault. We store each field separately in our Vault so that you can also refer to them specifically when needed, by using an alias.
  • A Record, on the other hand, is an entity linking multiple related fields together. It ensures the accuracy, consistency, and integrity of fields stored in the vault.

Records

Record Types

Each Record represents a specific type of data and groups relevant fields under a single identifier. For example, a Card Record consists of fields that are card number, security code, expiry date, and cardholder name, while a Network Token Record consists of fields that are network token, cryptogram, and expiry date.

You can immediately start storing available record types in Payrails Vault, such as Card and Network Token. If you would like to create a customized record for your business, you can request to add new record types to store records according to your custom record schema.

Usage of Records

Each record has its unique identifier (recordId), which you can refer to all fields as a group and manage their lifecycle more efficiently. For example, if a user wants to delete their card from your vault, instead of deleting the fields such as card number, expiry date one by one, you can delete the record by record id or delete the record by alias of one of its fields, which saves you from doing multiple operations. You can refer to our API reference on how to use the record id to get all the fields associated with it.

📘

Why are records important?

Maintains Data Integrity: Ensures all tokenized fields related to the same entity (e.g., a card or network token) remain linked.

Enhances Accuracy and Validity of Stored Values: Reduces the risk of mismatched or orphaned tokenized values by keeping all relevant fields connected.

Aliases

While combining all related fields by Record, we store each field separately in our Vault so that you can also refer to them specifically when you need. Each field stored in the vault is represented by an entity called alias, which is non-sensitive information used outside of the Vault to refer to the sensitive values stored in the Vault.

Each field has a type, a unique alias, a parent recordId, a recordType, and a displayableValue that the merchant decides while configuring the tokenization flow. You can fetch field information by using an alias of a field or multiple aliases. An example of fetching field details by multiple aliases can look like below.

{
	[
    {
      "recordId": "ba465782-f5a3-465b-9609-27a876b259de",
      "recordType": "card",
      "alias": "73dead56-8b69-4277-9a1b-a6994d22924b",
      "fieldType": "cardNumber",
      "displayableValue": "4111****1111"
    },
    {
      "recordId": "ba465782-f5a3-465b-9609-27a876b259de",
      "recordType": "card",
      "alias": "a927050e-75c6-4244-bfd8-ff6449a05781",
      "fieldType": "expiryYear",
      "displayableValue": "35"
    },
    {
      "recordId": "ba465782-f5a3-465b-9609-27a876b259de",
      "recordType": "card",
      "alias": "bee75a24-c588-4fda-a800-c921e2c0b04c",
      "fieldType": "expiryMonth",
      "displayableValue": "01"
    }
  ]
}

The field values stored in the Vault can be collected via our SDKs to collect information directly from the user or Proxy Connections, which enables tokenization flows between the merchant and third parties. To see how Records and Fields received via Proxy Connections are configured, visit our Proxy Connections guide.