Tokenize records

curl --request POST \
  --url https://api.vault.payrails.io/records/tokenize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "records": [
    {
      "type": "card",
      "fields": {
        "cardNumber": {
          "value": "4111111111111111"
        },
        "expiryMonth": {
          "value": "07"
        },
        "expiryYear": {
          "value": "29"
        },
        "holderName": {
          "value": "Max Mustermann"
        },
        "securityCode": {
          "value": "111"
        }
      }
    },
    {
      "type": "card",
      "fields": {
        "cardNumber": {
          "value": "1234"
        },
        "expiryMonth": {
          "value": "07"
        },
        "expiryYear": {
          "value": "29"
        },
        "holderName": {
          "value": "Erika Mustermann"
        }
      }
    }
  ]
}
'

import requests

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

payload = { "records": [
        {
            "type": "card",
            "fields": {
                "cardNumber": { "value": "4111111111111111" },
                "expiryMonth": { "value": "07" },
                "expiryYear": { "value": "29" },
                "holderName": { "value": "Max Mustermann" },
                "securityCode": { "value": "111" }
            }
        },
        {
            "type": "card",
            "fields": {
                "cardNumber": { "value": "1234" },
                "expiryMonth": { "value": "07" },
                "expiryYear": { "value": "29" },
                "holderName": { "value": "Erika Mustermann" }
            }
        }
    ] }
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({
    records: [
      {
        type: 'card',
        fields: {
          cardNumber: {value: '4111111111111111'},
          expiryMonth: {value: '07'},
          expiryYear: {value: '29'},
          holderName: {value: 'Max Mustermann'},
          securityCode: {value: '111'}
        }
      },
      {
        type: 'card',
        fields: {
          cardNumber: {value: '1234'},
          expiryMonth: {value: '07'},
          expiryYear: {value: '29'},
          holderName: {value: 'Erika Mustermann'}
        }
      }
    ]
  })
};

fetch('https://api.vault.payrails.io/records/tokenize', 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/tokenize",
  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([
    'records' => [
        [
                'type' => 'card',
                'fields' => [
                                'cardNumber' => [
                                                                'value' => '4111111111111111'
                                ],
                                'expiryMonth' => [
                                                                'value' => '07'
                                ],
                                'expiryYear' => [
                                                                'value' => '29'
                                ],
                                'holderName' => [
                                                                'value' => 'Max Mustermann'
                                ],
                                'securityCode' => [
                                                                'value' => '111'
                                ]
                ]
        ],
        [
                'type' => 'card',
                'fields' => [
                                'cardNumber' => [
                                                                'value' => '1234'
                                ],
                                'expiryMonth' => [
                                                                'value' => '07'
                                ],
                                'expiryYear' => [
                                                                'value' => '29'
                                ],
                                'holderName' => [
                                                                'value' => 'Erika Mustermann'
                                ]
                ]
        ]
    ]
  ]),
  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/tokenize"

	payload := strings.NewReader("{\n  \"records\": [\n    {\n      \"type\": \"card\",\n      \"fields\": {\n        \"cardNumber\": {\n          \"value\": \"4111111111111111\"\n        },\n        \"expiryMonth\": {\n          \"value\": \"07\"\n        },\n        \"expiryYear\": {\n          \"value\": \"29\"\n        },\n        \"holderName\": {\n          \"value\": \"Max Mustermann\"\n        },\n        \"securityCode\": {\n          \"value\": \"111\"\n        }\n      }\n    },\n    {\n      \"type\": \"card\",\n      \"fields\": {\n        \"cardNumber\": {\n          \"value\": \"1234\"\n        },\n        \"expiryMonth\": {\n          \"value\": \"07\"\n        },\n        \"expiryYear\": {\n          \"value\": \"29\"\n        },\n        \"holderName\": {\n          \"value\": \"Erika Mustermann\"\n        }\n      }\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/tokenize")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"records\": [\n    {\n      \"type\": \"card\",\n      \"fields\": {\n        \"cardNumber\": {\n          \"value\": \"4111111111111111\"\n        },\n        \"expiryMonth\": {\n          \"value\": \"07\"\n        },\n        \"expiryYear\": {\n          \"value\": \"29\"\n        },\n        \"holderName\": {\n          \"value\": \"Max Mustermann\"\n        },\n        \"securityCode\": {\n          \"value\": \"111\"\n        }\n      }\n    },\n    {\n      \"type\": \"card\",\n      \"fields\": {\n        \"cardNumber\": {\n          \"value\": \"1234\"\n        },\n        \"expiryMonth\": {\n          \"value\": \"07\"\n        },\n        \"expiryYear\": {\n          \"value\": \"29\"\n        },\n        \"holderName\": {\n          \"value\": \"Erika Mustermann\"\n        }\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"records\": [\n    {\n      \"type\": \"card\",\n      \"fields\": {\n        \"cardNumber\": {\n          \"value\": \"4111111111111111\"\n        },\n        \"expiryMonth\": {\n          \"value\": \"07\"\n        },\n        \"expiryYear\": {\n          \"value\": \"29\"\n        },\n        \"holderName\": {\n          \"value\": \"Max Mustermann\"\n        },\n        \"securityCode\": {\n          \"value\": \"111\"\n        }\n      }\n    },\n    {\n      \"type\": \"card\",\n      \"fields\": {\n        \"cardNumber\": {\n          \"value\": \"1234\"\n        },\n        \"expiryMonth\": {\n          \"value\": \"07\"\n        },\n        \"expiryYear\": {\n          \"value\": \"29\"\n        },\n        \"holderName\": {\n          \"value\": \"Erika Mustermann\"\n        }\n      }\n    }\n  ]\n}"

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

{
  "records": [
    {
      "id": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
      "type": "card",
      "fingerprint": "58f969bd-1e3a-49cc-ada6-e86e184b976b",
      "fields": [
        {
          "alias": "02ee96e9-b740-469e-a382-f47255393a92",
          "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
          "recordType": "card",
          "fieldType": "cardNumber",
          "displayableValue": "xxxxxxxxxxxx1111"
        },
        {
          "alias": "dc51b23c-7c1e-4a9e-9d67-1f0f1a3f1b52",
          "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
          "recordType": "card",
          "fieldType": "expiryMonth",
          "displayableValue": "07"
        },
        {
          "alias": "9b41f0a6-2d64-4a2e-8f1e-0c2a1b3d4e5f",
          "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
          "recordType": "card",
          "fieldType": "expiryYear",
          "displayableValue": "29"
        },
        {
          "alias": "7c2d8e19-5a3b-4c6d-9e0f-1a2b3c4d5e6f",
          "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
          "recordType": "card",
          "fieldType": "holderName",
          "displayableValue": "Max Mustermann"
        },
        {
          "alias": "4e762a38-8b00-49f8-a484-42d29bac3a9b",
          "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
          "recordType": "card",
          "fieldType": "securityCode",
          "displayableValue": "xxx",
          "hasValue": true,
          "maximumExpirationDate": "2026-09-08T12:00:00Z"
        }
      ]
    },
    {
      "error": {
        "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
        "code": "request.param.invalid",
        "detail": "The card number is invalid",
        "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestparaminvalid"
      }
    }
  ]
}

{
  "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"
    }
  ]
}

Tokenize records

Store card or network token data in the Payrails Vault and receive aliases for it.

The response returns one entry per requested record, in the order of the request, in the same representation the record retrieval endpoints return. A record that fails validation carries an error and does not fail the rest of the request.

A request holds at most 50 records. One carrying more is rejected with 413 and no record is stored.

Repeating a request stores new records and returns new aliases. The endpoint provides no idempotency.

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

tokenize

Tokenize records

curl --request POST \
  --url https://api.vault.payrails.io/records/tokenize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "records": [
    {
      "type": "card",
      "fields": {
        "cardNumber": {
          "value": "4111111111111111"
        },
        "expiryMonth": {
          "value": "07"
        },
        "expiryYear": {
          "value": "29"
        },
        "holderName": {
          "value": "Max Mustermann"
        },
        "securityCode": {
          "value": "111"
        }
      }
    },
    {
      "type": "card",
      "fields": {
        "cardNumber": {
          "value": "1234"
        },
        "expiryMonth": {
          "value": "07"
        },
        "expiryYear": {
          "value": "29"
        },
        "holderName": {
          "value": "Erika Mustermann"
        }
      }
    }
  ]
}
'

import requests

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

payload = { "records": [
        {
            "type": "card",
            "fields": {
                "cardNumber": { "value": "4111111111111111" },
                "expiryMonth": { "value": "07" },
                "expiryYear": { "value": "29" },
                "holderName": { "value": "Max Mustermann" },
                "securityCode": { "value": "111" }
            }
        },
        {
            "type": "card",
            "fields": {
                "cardNumber": { "value": "1234" },
                "expiryMonth": { "value": "07" },
                "expiryYear": { "value": "29" },
                "holderName": { "value": "Erika Mustermann" }
            }
        }
    ] }
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({
    records: [
      {
        type: 'card',
        fields: {
          cardNumber: {value: '4111111111111111'},
          expiryMonth: {value: '07'},
          expiryYear: {value: '29'},
          holderName: {value: 'Max Mustermann'},
          securityCode: {value: '111'}
        }
      },
      {
        type: 'card',
        fields: {
          cardNumber: {value: '1234'},
          expiryMonth: {value: '07'},
          expiryYear: {value: '29'},
          holderName: {value: 'Erika Mustermann'}
        }
      }
    ]
  })
};

fetch('https://api.vault.payrails.io/records/tokenize', 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/tokenize",
  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([
    'records' => [
        [
                'type' => 'card',
                'fields' => [
                                'cardNumber' => [
                                                                'value' => '4111111111111111'
                                ],
                                'expiryMonth' => [
                                                                'value' => '07'
                                ],
                                'expiryYear' => [
                                                                'value' => '29'
                                ],
                                'holderName' => [
                                                                'value' => 'Max Mustermann'
                                ],
                                'securityCode' => [
                                                                'value' => '111'
                                ]
                ]
        ],
        [
                'type' => 'card',
                'fields' => [
                                'cardNumber' => [
                                                                'value' => '1234'
                                ],
                                'expiryMonth' => [
                                                                'value' => '07'
                                ],
                                'expiryYear' => [
                                                                'value' => '29'
                                ],
                                'holderName' => [
                                                                'value' => 'Erika Mustermann'
                                ]
                ]
        ]
    ]
  ]),
  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/tokenize"

	payload := strings.NewReader("{\n  \"records\": [\n    {\n      \"type\": \"card\",\n      \"fields\": {\n        \"cardNumber\": {\n          \"value\": \"4111111111111111\"\n        },\n        \"expiryMonth\": {\n          \"value\": \"07\"\n        },\n        \"expiryYear\": {\n          \"value\": \"29\"\n        },\n        \"holderName\": {\n          \"value\": \"Max Mustermann\"\n        },\n        \"securityCode\": {\n          \"value\": \"111\"\n        }\n      }\n    },\n    {\n      \"type\": \"card\",\n      \"fields\": {\n        \"cardNumber\": {\n          \"value\": \"1234\"\n        },\n        \"expiryMonth\": {\n          \"value\": \"07\"\n        },\n        \"expiryYear\": {\n          \"value\": \"29\"\n        },\n        \"holderName\": {\n          \"value\": \"Erika Mustermann\"\n        }\n      }\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/tokenize")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"records\": [\n    {\n      \"type\": \"card\",\n      \"fields\": {\n        \"cardNumber\": {\n          \"value\": \"4111111111111111\"\n        },\n        \"expiryMonth\": {\n          \"value\": \"07\"\n        },\n        \"expiryYear\": {\n          \"value\": \"29\"\n        },\n        \"holderName\": {\n          \"value\": \"Max Mustermann\"\n        },\n        \"securityCode\": {\n          \"value\": \"111\"\n        }\n      }\n    },\n    {\n      \"type\": \"card\",\n      \"fields\": {\n        \"cardNumber\": {\n          \"value\": \"1234\"\n        },\n        \"expiryMonth\": {\n          \"value\": \"07\"\n        },\n        \"expiryYear\": {\n          \"value\": \"29\"\n        },\n        \"holderName\": {\n          \"value\": \"Erika Mustermann\"\n        }\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"records\": [\n    {\n      \"type\": \"card\",\n      \"fields\": {\n        \"cardNumber\": {\n          \"value\": \"4111111111111111\"\n        },\n        \"expiryMonth\": {\n          \"value\": \"07\"\n        },\n        \"expiryYear\": {\n          \"value\": \"29\"\n        },\n        \"holderName\": {\n          \"value\": \"Max Mustermann\"\n        },\n        \"securityCode\": {\n          \"value\": \"111\"\n        }\n      }\n    },\n    {\n      \"type\": \"card\",\n      \"fields\": {\n        \"cardNumber\": {\n          \"value\": \"1234\"\n        },\n        \"expiryMonth\": {\n          \"value\": \"07\"\n        },\n        \"expiryYear\": {\n          \"value\": \"29\"\n        },\n        \"holderName\": {\n          \"value\": \"Erika Mustermann\"\n        }\n      }\n    }\n  ]\n}"

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

{
  "records": [
    {
      "id": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
      "type": "card",
      "fingerprint": "58f969bd-1e3a-49cc-ada6-e86e184b976b",
      "fields": [
        {
          "alias": "02ee96e9-b740-469e-a382-f47255393a92",
          "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
          "recordType": "card",
          "fieldType": "cardNumber",
          "displayableValue": "xxxxxxxxxxxx1111"
        },
        {
          "alias": "dc51b23c-7c1e-4a9e-9d67-1f0f1a3f1b52",
          "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
          "recordType": "card",
          "fieldType": "expiryMonth",
          "displayableValue": "07"
        },
        {
          "alias": "9b41f0a6-2d64-4a2e-8f1e-0c2a1b3d4e5f",
          "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
          "recordType": "card",
          "fieldType": "expiryYear",
          "displayableValue": "29"
        },
        {
          "alias": "7c2d8e19-5a3b-4c6d-9e0f-1a2b3c4d5e6f",
          "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
          "recordType": "card",
          "fieldType": "holderName",
          "displayableValue": "Max Mustermann"
        },
        {
          "alias": "4e762a38-8b00-49f8-a484-42d29bac3a9b",
          "recordId": "05eeb10a-cfb6-47e7-86ee-62e14c2a7e05",
          "recordType": "card",
          "fieldType": "securityCode",
          "displayableValue": "xxx",
          "hasValue": true,
          "maximumExpirationDate": "2026-09-08T12:00:00Z"
        }
      ]
    },
    {
      "error": {
        "id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
        "code": "request.param.invalid",
        "detail": "The card number is invalid",
        "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestparaminvalid"
      }
    }
  ]
}

{
  "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

Records to tokenize.

records

Record to tokenize · object[]

required

Records to tokenize. A request holds at least 1 and at most 50 records; a request carrying more is rejected with 413 before any record is stored.

Required array length: 1 - 50 elements

Hide child attributes

records.type

enum<string>

required

Type of the record to create.

Available options:

card,

networkToken

Example:

"card"

records.fields

object

required

Values to tokenize, keyed by field type. Allowed keys depend on the record type:

card: cardNumber, expiryMonth, expiryYear, holderName, securityCode.
networkToken: networkToken, expiryMonth, expiryYear, cryptogram.

securityCode and cryptogram are stored as volatile fields and expire according to your vault configuration. Their retention cannot be set per request.

Hide child attributes

records.fields.{key}

Field value · object

Hide child attributes

records.fields.{key}.value

string

required

The value to tokenize.

Example:

{
  "cardNumber": { "value": "4111111111111111" },
  "expiryMonth": { "value": "07" },
  "expiryYear": { "value": "29" },
  "holderName": { "value": "Max Mustermann" },
  "securityCode": { "value": "111" }
}

Response

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

records

Tokenization result · object[]

required

One entry per requested record, in the order of the request. A record that cannot be stored carries an error and does not fail the rest of the request.

Hide child attributes

records.id

string<uuid>

Payrails unique identifier of the record.

records.type

string

Type of this record, e.g. card or networkToken.

records.fingerprint

string

The fingerprint of the record. Depending on type can be used to match with other records.

records.fields

Field object · object[]

Fields belong to this record.

Hide child attributes

records.fields.alias

string

Merchant-facing unique alias for the field. Used as an identifier.

records.fields.recordId

string

Identifier of the record to which the alias belongs.

records.fields.recordType

string

Record type to which this field belongs, e.g. card and networkToken.

records.fields.fieldType

string

Field type of the alias, e.g. cardNumber, expiryMonth, expiryYear, securityCode, holderName, networkToken, cryptogram.

records.fields.displayableValue

string | null

Displayable value for the field.

records.fields.allowedDetokenizationCount

integer | null

It will be restricted if used on a proxy and reaches the limit mentioned in this field.

Example:

0

records.fields.allowedSdkRevealCount

integer | null

It will be restricted if used on a SDK reveal and reaches the limit mentioned in this field.

Example:

0

records.fields.hasValue

boolean | null

Indicates whether the volatile field has a value associated with it. If false or not present, the field has been deleted or was never set.

records.fields.maximumExpirationDate

string<date-time> | null

The maximum expiration date for the volatile field value. After this date, the field value will be deleted. Please note that depending on usage of volatile field, value can be deleted even earlier, for example if allowed detokenization or reveal counts are exceeded, or when you explicitly call delete operation on the field.

Example:

"2024-12-31T23:59:59Z"

records.fields.detokenizations

Detokenization attempts. · object[] | null

List of detokenization attempts performed on this field. This field is returned only when requested via includeDetokenizations query parameter.

Hide child attributes

records.fields.detokenizations.lastAttemptedAt

string<date-time>

Timestamp when the detokenization was attempted.

Example:

"2024-01-01T12:00:00Z"

records.fields.detokenizations.count

integer

Number of times this type of detokenization was successfully performed.

Example:

1

records.fields.detokenizations.type

enum<string>

Type of detokenization attempt. detokenization indicates a standard detokenization, while sdkReveal indicates a detokenization performed via SDK reveal.

Available options:

detokenization,

sdkReveal

Example:

"detokenization"

records.error

object

Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation here.

Hide child attributes

records.error.id

string<uuid>

required

Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster.

records.error.code

string

required

Machine-friendly error code assigned to the error. Check the full list of possible values here.

records.error.detail

string

required

Human-readable description about the error, its cause, and resolution.

records.error.docUrl

string

Link to the specific documentation about this particular code.

records.error.reason

object

Metadata providing more details about the reason of the error. The structure of this object varies according to the code.

Last modified on October 7, 2026

Payrails API Reference

Get started

Workflow

Payment

Provider

Merchant

Vault

Analytics

Reporting

Reconciliation

Dispute

Tokenize records

Authorizations

Body

Response