When starting with Payrails, our Vault allows you to import already existing instruments from other Vaults or PSPs so that you can process payments without disturbing your 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.

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

• Your customers can use their stored payment methods with no interruption
• Your PSPs currently processing 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 instrument in 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.

Import

For importing instruments into Payrails Vault, you have the following two options:

• send instruments via our Create an instrument API
• add tokens to existing instruments via our Create a token API

After this is done, your users can continue adding instruments or tokens via our Components and SDK for Web or Mobile.

For example, the following is a request for adding an instrument and its token at the same time.

{
  "holderId": "788c7c09-a490-4603-915a-e2a957a6cca1",
  "storeInstrument": true,
  "paymentMethod": "card",
  "description": "personal card",
  "futureUsage": "CardOnFile",
  "data": {
    "network": "visa",
    "bin": "411111",
    "suffix": "1111",
    "expiryMonth": "10",
    "expiryYear": "2026",
    "holderName": "John Doe",
    "issuer": "SomeBank",
    "issuerCountry": {
      "code": "DE"
    }
  },
  "meta": {
    "communityCode": "GAP",
    "userKey": "9890124569"
  },
  "token": {
    "providerId": "e0ba44eb-1d54-4317-823b-d2f9419d3b9d",
    "reference": "token-in-the-provider",
    "type": "network"
  }
}

Then, the response will look like:

{
  "id": "b8fe6271-5d71-4d28-b8e8-89e64acc0c49",
  "holderId": "788c7c09-a490-4603-915a-e2a957a6cca1",
  "createdAt": "2022-04-22T17:53:36.814Z",
  "paymentMethod": "card",
  "description": "Personal card.",
  "fingerprint": "739abff0-406a-4d32-8cfb-701e12be5848",
  "status": "created",
  "data": {
    "network": "visa",
    "bin": "411111",
    "suffix": "1111",
    "expiryMonth": "10",
    "expiryYear": "2026",
    "holderName": "John Doe"
  },
  "tokens": [
    {
      "id": "5671c2cc-32c4-437d-a830-c449db87c542",
      "createdAt": "2022-04-22T17:53:36.814Z",
      "instrumentId": "b8fe6271-5d71-4d28-b8e8-89e64acc0c49",
      "status": "created",
      "type": "network",
      "providerId": "e0ba44eb-1d54-4317-823b-d2f9419d3b9d",
      "providerConfigId": "69e0aac4-2939-427e-aa37-d79e4989219c",
      "reference": "token-in-the-provider",
      "meta": {
        "extraKey": "extraValue"
      }
    }
  ]
}

Export

Every instrument in our Vault is accessible via our APIs for listing instruments and tokens.

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).