Detokenize records and aliases

curl --request POST \
  --url https://api.vault.payrails.io/records/detokenize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05"
    },
    {
      "recordAlias": "8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90"
    },
    {
      "alias": "02ee96e9-b740-469e-a382-f47255393a92"
    },
    {
      "alias": "4e762a38-8b00-49f8-a484-42d29bac3a9b"
    }
  ]
}
'

import requests

url = "https://api.vault.payrails.io/records/detokenize"

payload = { "items": [{ "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05" }, { "recordAlias": "8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90" }, { "alias": "02ee96e9-b740-469e-a382-f47255393a92" }, { "alias": "4e762a38-8b00-49f8-a484-42d29bac3a9b" }] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {recordId: '05eeb10a-cfb6-47e7-86ee-62e14c2a7e05'},
      {recordAlias: '8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90'},
      {alias: '02ee96e9-b740-469e-a382-f47255393a92'},
      {alias: '4e762a38-8b00-49f8-a484-42d29bac3a9b'}
    ]
  })
};

fetch('https://api.vault.payrails.io/records/detokenize', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vault.payrails.io/records/detokenize",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'items' => [
        [
                'recordId' => '05eeb10a-cfb6-47e7-86ee-62e14c2a7e05'
        ],
        [
                'recordAlias' => '8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90'
        ],
        [
                'alias' => '02ee96e9-b740-469e-a382-f47255393a92'
        ],
        [
                'alias' => '4e762a38-8b00-49f8-a484-42d29bac3a9b'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vault.payrails.io/records/detokenize"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"recordId\": \"05eeb10a-cfb6-47e7-86ee-62e14c2a7e05\"\n    },\n    {\n      \"recordAlias\": \"8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90\"\n    },\n    {\n      \"alias\": \"02ee96e9-b740-469e-a382-f47255393a92\"\n    },\n    {\n      \"alias\": \"4e762a38-8b00-49f8-a484-42d29bac3a9b\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vault.payrails.io/records/detokenize")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"recordId\": \"05eeb10a-cfb6-47e7-86ee-62e14c2a7e05\"\n    },\n    {\n      \"recordAlias\": \"8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90\"\n    },\n    {\n      \"alias\": \"02ee96e9-b740-469e-a382-f47255393a92\"\n    },\n    {\n      \"alias\": \"4e762a38-8b00-49f8-a484-42d29bac3a9b\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vault.payrails.io/records/detokenize")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"recordId\": \"05eeb10a-cfb6-47e7-86ee-62e14c2a7e05\"\n    },\n    {\n      \"recordAlias\": \"8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90\"\n    },\n    {\n      \"alias\": \"02ee96e9-b740-469e-a382-f47255393a92\"\n    },\n    {\n      \"alias\": \"4e762a38-8b00-49f8-a484-42d29bac3a9b\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
      "type": "card",
      "fields": [
        {
          "alias": "02ee96e9-b740-469e-a382-f47255393a92",
          "fieldType": "cardNumber",
          "value": "4111111111111111"
        },
        {
          "alias": "dc51b23c-7c1e-4a9e-9d67-1f0f1a3f1b52",
          "fieldType": "expiryMonth",
          "value": "07"
        },
        {
          "alias": "9b41f0a6-2d64-4a2e-8f1e-0c2a1b3d4e5f",
          "fieldType": "expiryYear",
          "value": "29"
        }
      ]
    },
    {
      "recordId": "6d0f2b48-1e93-4c7a-8b25-3f9a0d1c2e34",
      "type": "networkToken",
      "fields": [
        {
          "alias": "8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90",
          "fieldType": "networkToken",
          "value": "5204731000000001"
        },
        {
          "alias": "b7e14c50-3a29-4d6b-8f71-0c9e2a5d3b48",
          "fieldType": "cryptogram",
          "value": "AgAAAAAABk4DeSbAgAAAAAAAAA="
        }
      ]
    },
    {
      "alias": "02ee96e9-b740-469e-a382-f47255393a92",
      "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
      "recordType": "card",
      "fieldType": "cardNumber",
      "value": "4111111111111111"
    },
    {
      "alias": "4e762a38-8b00-49f8-a484-42d29bac3a9b",
      "error": {
        "id": "9f1c8b7a-4d2e-4c31-9a08-5b6d7e8f9a0b",
        "code": "vault.field.not-available",
        "detail": "The field holds no value that can be revealed"
      }
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.malformed",
      "detail": "The request has malformed syntax",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestmalformed"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.unauthorized",
      "detail": "The request lacks necessary credentials to perform the specified action",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestunauthorized"
    }
  ]
}

{
  "errors": [
    {
      "id": "e7db22b3-914e-4975-928e-9edfb0885bea",
      "code": "request.forbidden",
      "detail": "The request credentials lack the required permissions to perform the specified action",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestforbidden"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.not-found",
      "detail": "The requested resource was not found",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestnot-found"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.entity-too-large",
      "detail": "The request entity is too large",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestentity-too-large"
    }
  ]
}

{
  "errors": [
    {
      "id": "07a1d642-dbf5-47d3-8563-700514b38e46",
      "code": "request.header.missing",
      "detail": "The request is missing a required header",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestheadermissing"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "service.unavailable",
      "detail": "The requested service is currently unavailable",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#serviceunavailable"
    }
  ]
}

Detokenize records and aliases

Reveal data stored in the Payrails Vault. An item is addressed by record identifier, by record alias, or by field alias, and a single request can mix all three.

The response returns one entry per requested item. Match a result to what you sent by the keys it carries rather than by its position - a failed item echoes the key it was addressed by. An item that cannot be resolved carries an error and does not fail the rest of the request:

request.not-found: nothing matches the key the item was addressed by. The detail says which key that was - recordId, recordAlias or alias.
vault.field.not-available: the field holds no value that can be revealed - it was never given one, it expired out of volatile storage, or it reached the number of reveals allowed for it. A record addressed by recordId or recordAlias reports this only when none of its fields could be revealed; otherwise it comes back with the fields that could.

A request holds at most 50 items. One carrying more is rejected with 413 and nothing is revealed.

Every reveal counts against what the field is allowed, so a record addressed by several items of one request is revealed once - repeating an item costs no more of that allowance than asking once does.

This endpoint is served on the Payrails Vault host and accepts a Vault access token. It is available by request and requires an approval by Payrails.

POST

https://api.vault.payrails.io

records

detokenize

Detokenize records and aliases

curl --request POST \
  --url https://api.vault.payrails.io/records/detokenize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05"
    },
    {
      "recordAlias": "8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90"
    },
    {
      "alias": "02ee96e9-b740-469e-a382-f47255393a92"
    },
    {
      "alias": "4e762a38-8b00-49f8-a484-42d29bac3a9b"
    }
  ]
}
'

import requests

url = "https://api.vault.payrails.io/records/detokenize"

payload = { "items": [{ "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05" }, { "recordAlias": "8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90" }, { "alias": "02ee96e9-b740-469e-a382-f47255393a92" }, { "alias": "4e762a38-8b00-49f8-a484-42d29bac3a9b" }] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {recordId: '05eeb10a-cfb6-47e7-86ee-62e14c2a7e05'},
      {recordAlias: '8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90'},
      {alias: '02ee96e9-b740-469e-a382-f47255393a92'},
      {alias: '4e762a38-8b00-49f8-a484-42d29bac3a9b'}
    ]
  })
};

fetch('https://api.vault.payrails.io/records/detokenize', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vault.payrails.io/records/detokenize",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'items' => [
        [
                'recordId' => '05eeb10a-cfb6-47e7-86ee-62e14c2a7e05'
        ],
        [
                'recordAlias' => '8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90'
        ],
        [
                'alias' => '02ee96e9-b740-469e-a382-f47255393a92'
        ],
        [
                'alias' => '4e762a38-8b00-49f8-a484-42d29bac3a9b'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vault.payrails.io/records/detokenize"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"recordId\": \"05eeb10a-cfb6-47e7-86ee-62e14c2a7e05\"\n    },\n    {\n      \"recordAlias\": \"8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90\"\n    },\n    {\n      \"alias\": \"02ee96e9-b740-469e-a382-f47255393a92\"\n    },\n    {\n      \"alias\": \"4e762a38-8b00-49f8-a484-42d29bac3a9b\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vault.payrails.io/records/detokenize")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"recordId\": \"05eeb10a-cfb6-47e7-86ee-62e14c2a7e05\"\n    },\n    {\n      \"recordAlias\": \"8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90\"\n    },\n    {\n      \"alias\": \"02ee96e9-b740-469e-a382-f47255393a92\"\n    },\n    {\n      \"alias\": \"4e762a38-8b00-49f8-a484-42d29bac3a9b\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vault.payrails.io/records/detokenize")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"recordId\": \"05eeb10a-cfb6-47e7-86ee-62e14c2a7e05\"\n    },\n    {\n      \"recordAlias\": \"8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90\"\n    },\n    {\n      \"alias\": \"02ee96e9-b740-469e-a382-f47255393a92\"\n    },\n    {\n      \"alias\": \"4e762a38-8b00-49f8-a484-42d29bac3a9b\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
      "type": "card",
      "fields": [
        {
          "alias": "02ee96e9-b740-469e-a382-f47255393a92",
          "fieldType": "cardNumber",
          "value": "4111111111111111"
        },
        {
          "alias": "dc51b23c-7c1e-4a9e-9d67-1f0f1a3f1b52",
          "fieldType": "expiryMonth",
          "value": "07"
        },
        {
          "alias": "9b41f0a6-2d64-4a2e-8f1e-0c2a1b3d4e5f",
          "fieldType": "expiryYear",
          "value": "29"
        }
      ]
    },
    {
      "recordId": "6d0f2b48-1e93-4c7a-8b25-3f9a0d1c2e34",
      "type": "networkToken",
      "fields": [
        {
          "alias": "8f3a1c7d-6b2e-4f80-9a51-2d7c4e6b8a90",
          "fieldType": "networkToken",
          "value": "5204731000000001"
        },
        {
          "alias": "b7e14c50-3a29-4d6b-8f71-0c9e2a5d3b48",
          "fieldType": "cryptogram",
          "value": "AgAAAAAABk4DeSbAgAAAAAAAAA="
        }
      ]
    },
    {
      "alias": "02ee96e9-b740-469e-a382-f47255393a92",
      "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
      "recordType": "card",
      "fieldType": "cardNumber",
      "value": "4111111111111111"
    },
    {
      "alias": "4e762a38-8b00-49f8-a484-42d29bac3a9b",
      "error": {
        "id": "9f1c8b7a-4d2e-4c31-9a08-5b6d7e8f9a0b",
        "code": "vault.field.not-available",
        "detail": "The field holds no value that can be revealed"
      }
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.malformed",
      "detail": "The request has malformed syntax",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestmalformed"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.unauthorized",
      "detail": "The request lacks necessary credentials to perform the specified action",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestunauthorized"
    }
  ]
}

{
  "errors": [
    {
      "id": "e7db22b3-914e-4975-928e-9edfb0885bea",
      "code": "request.forbidden",
      "detail": "The request credentials lack the required permissions to perform the specified action",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestforbidden"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.not-found",
      "detail": "The requested resource was not found",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestnot-found"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "request.entity-too-large",
      "detail": "The request entity is too large",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestentity-too-large"
    }
  ]
}

{
  "errors": [
    {
      "id": "07a1d642-dbf5-47d3-8563-700514b38e46",
      "code": "request.header.missing",
      "detail": "The request is missing a required header",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestheadermissing"
    }
  ]
}

{
  "errors": [
    {
      "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
      "code": "service.unavailable",
      "detail": "The requested service is currently unavailable",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#serviceunavailable"
    }
  ]
}

Authorizations

Authorization

string

header

required

You can use an OAuth2 JWT bearer token in the Authorization header of your API requests for supported endpoints: Authorization: Bearer <YOUR_JWT_HERE>. These tokens are short-lived (the exact lifetime is returned in expires_in) and can be requested via the vault access token endpoint. They are accepted only on the Payrails Vault host and grant access to the tokenization and detokenization endpoints.

Body

application/json

Items to detokenize.

items

(Record by ID. · object | Record by alias. · object | Field by alias. · object)[]

required

Items to reveal. A request holds at least 1 and at most 50 items. Records and aliases can be mixed in one request, and the same record or alias may be addressed by more than one item - each item gets its own result, and the record is revealed once however many items ask for it.

Required array length: 1 - 50 elements

A single item to reveal, addressed by exactly one key. The three addressing modes mirror the record retrieval endpoints: a whole record by its identifier, a whole record by the alias of one of its fields, or a single field by its alias.

Record by ID.
Record by alias.
Field by alias.

Hide child attributes

items.recordId

string<uuid>

required

Payrails unique identifier of the record to reveal.

Example:

"05eeb10a-cfb6-47e7-86ee-62e14c2a7e05"

Response

Detokenization completed. Check per-item errors in the response.

items

(Record. · object | Field by alias. · object | Failed item. · object)[]

required

One entry per requested item. The order in which items are returned may not match the order in which you passed them. An item that cannot be resolved carries an error and does not fail the rest of the request.

Result for a single requested item. It carries either the revealed data or an error, never both.

A record addressed by alias comes back the same way as a record addressed by its identifier: the alias it was addressed by appears among the fields of the record.

Record.
Field by alias.
Failed item.

Hide child attributes

items.recordId

string<uuid>

required

Identifier of the revealed record.

items.type

string

required

Type of the record, for example card or networkToken.

items.fields

Detokenized field · object[]

required

Every field of the record, with its value in clear text.

Hide child attributes

items.fields.alias

string

required

Merchant-facing unique alias for the field.

Example:

"02ee96e9-b740-469e-a382-f47255393a92"

items.fields.fieldType

string

required

Field type of the alias, for example cardNumber, expiryMonth, expiryYear, securityCode, holderName, networkToken, cryptogram.

Example:

"cardNumber"

items.fields.value

string

required

Value of the field in clear text.

Example:

"4111111111111111"

Last modified on October 7, 2026

Payrails API Reference

Get started

Workflow

Payment

Provider

Merchant

Vault

Analytics

Reporting

Reconciliation

Dispute

Detokenize records and aliases

Authorizations

Body

Response