Migrate tokens

When starting or working with Payrails, our Vault allows you to import existing payment instruments from other Vaults or PSPs to process payments without creating friction for users by entering their instrument information again.

Also, if at any time you need to export the data contained in Payrails Vault, you can easily access it too. Keep in mind that in this case, the full PAN for cards will not be exported by default, because of our PCI compliance at every endpoint. If you need the full PAN, please contact our team to get more information on the specific process that we will follow in compliance with PCI DSS.

There are many benefits of importing your existing payment instruments when starting with Payrails, for example:

  • Your customers can use their stored payment methods with no interruption
  • PSPs that are currently processing your payments don't need to create new accounts and configurations
  • You control how many tokens you have for a specific instrument of a user

When importing an existing payment instrument from other Vaults or PSPs, Payrails performs a uniqueness check and groups every possible representation of the same instrument into one instrument with many tokens in different providers. This way, when performing a payment, we can choose which token is the best to increase conversion by rules and routing.

Securely import sensitive card data

This section provides a step-by-step process to migrate tokens from other vault providers or payment service providers (PSP) into the Payrails Token Vault. Our secure, PCI DSS-certified token vault ensures the highest level of security for your sensitive payment data.

Prerequisites

Before we begin the migration process, Payrails, the merchant, and the provider that the tokens will be migrated from will align on the process, the method of the data transfer, and the structure of the token file. We ensure compliance with PCI DSS and other relevant regulations during the migration process.

Step 1: Initiate the process on the current provider

First, your account owner should contact the provider to initiate the token migration process. Depending on the provider, the process changes (i.e. starting the process via a merchant dashboard or sending an email). You can consult your Payrails account representative to understand the process for the provider that you wish to initiate the process, and we will guide you to initiate the process. Due to compliance, the current provider will require Payrails' PCI Attestation of Compliance (AOC), which we will provide during this step.

Step 2: Prepare the data

At this step, you need to prepare the token data with the help of your current provider. This involves exporting the data in a format that can be ingested by Payrails. Typically, this includes token identifier, associated payment card data, and metadata (e.g., customer ID). We will align with the provider with the specific format of their file as well as the file transfer methods that will be used. In addition to the token file from the provider, we will need a file to ensure correct mapping of the instruments to your customers. Your Payrails account representative will also guide you on the file format and file transfer method at this step.

Step 3: Transfer the data

To ensure the security of your data during the migration, we use secure file transfer protocol and security practices recommended for large data sets. At this step, typically provider will require certain keys from Payrails for the data encryption, where your Payrails account representative will be involved in coordinating.

Step 4: Verify and run the migration

Once the data is transferred to Payrails, our system first verifies the integrity, validity, and accuracy of the tokens received. After validation checks, the tokens will be created in the Payrails secure vault and we will create payment instruments in Payrails system which the tokens will be attached to. See more details about relation of payment instruments and tokens in Instruments guide.

Step 5: Import the result file

After this step, Payrails will generate and share a result file with the merchant. The merchant will import the result file into their system for the mapping of the payment instruments with new tokens and their holders. This will ensure the mapping of new instruments in all systems.

Migrating your tokens to Payrails ensures that you benefit from our secure, PCI DSS-certified token vault. For any questions or assistance, please contact our support or your account representative.

Request a card data export

Every instrument in our Vault is accessible via our APIs for listing instruments and tokens. If you want to migrate tokens as a batch from Payrails to another provider, please contact Payrails support. We will start a process where we coordinate the migration with the provider that you wish to migrate the tokens to, ensuring the PCI DSS compliance and security of the token migration process.

If you want to export the tokens for a specific instrument, you can use the Search & list tokens API, which allows you to filter and paginate the list as desired. In case you need a more general export for many instruments, you should use the Search & list instruments API.

If you need both instruments and tokens in the same response, you should use the includeTokens optional query parameter in the Search & list instruments API. Take into account that these operations can become heavier the more data you have in our Vault. Therefore, you should make use of filtering and paging as much as possible. The following is an example of filtering for a given holder (filter[holderReference]=some-reference) to list their instruments and tokens (includeTokens=true).