> ## Documentation Index > Fetch the complete documentation index at: https://docs.payrails.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code. > Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it. > Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code. > Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation. > Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent. > Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format. > Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code. # 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. ## OpenAPI ````yaml https://cdn.payrails.io/docs/api/openapi.min.json?nav=vault post /records/tokenize openapi: 3.1.0 info: version: 1.3.15 title: Payrails API Reference contact: name: Payrails url: https://www.payrails.com email: tech@payrails.com license: name: Payrails GmbH url: https://www.payrails.com/ description: > --- Payrails provides a collection of APIs that enable you to process and manage payments. Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using your favorite HTTP/REST library. servers: - url: https://api.staging.payrails.io description: Payrails environment. security: - ApiKey: [] tags: - name: 3D Secure description: Operations to monitor 3DS operations. - name: Actions description: >- A workflow execution action is a predefined interaction that can be triggered to change the state of the workflow execution. For example authorizing or refunding a payment. - name: API Logs description: API Logs. - name: Authentication description: >- Payrails API is secured via [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) industry-standard protocol for authorization. Server-side requests are authenticated using a [Bearer Token](https://datatracker.ietf.org/doc/html/rfc6750) in the request `Authorization` header. - name: BIN Lookup description: >- Operations related to getting information about a card by its BIN (or IIN). - name: Client description: Endpoints used by our client-side SDK. - name: Disputes description: Operations to managing disputes. - name: Drop-in Links description: >- Create and manage drop-in payment links that can be shared with payers. Drop-in links support full or partial payments, define the total amount and expiration, and return a public URL that merchants can send to customers. - name: Executions description: >- A workflow execution is an act of performing a set of tasks that are defined in the [Workflow](/api-reference/reference/#operation/listDefaultWorkflows) such as accepting payments. - name: Files description: Operations related to files processing - name: Fraud Checks description: >- A Fraud check Payrails is a collection of operations over time, that is created by a workflow execution and followed by the workflow actions. In this section, you can list all the fraud entities or a single one to learn about the details of involved instruments, providers, statuses, decisions and more. - name: Holders description: >- A Holder is a group of accounts that belong together with specific criteria, linked to their payment instruments and identities. For example, it can represent a digital wallet for a person, where they store balance that they top up, refunded orders, referral bonuses, etc. - name: Instrument Tokens description: >- Tokens are representations of our payment instruments in external providers. One payment instrument can have many tokens, because we keep the mapping in each external provider that knows about it. For example, the same real life card can have a token in our Vault, but also in Adyen and Checkout PSPs. - name: Instruments description: >- Payment instruments are specific instances of a payment method that belong to the holder executing the workflow. They can be a previously stored card, a new card that was typed in a form, a phone number, an IBAN, or some way to fetch an account in a provider (like PayPal or AliPay). - name: Payments description: >- A [Payment](/guides/whats-payrails/payments/) in Payrails is a collection of operations over time, that is created by a workflow execution and followed by the workflow actions. In this section, you can list all the payments or a single one to learn about the details of involved payment methods, instruments, providers, statuses and more. - name: Payouts description: Payouts are money movements paid to an external party. - name: Provider Configs description: Operations related to managing configurations for Providers. - name: Providers description: Operations related to managing Providers. - name: Reconciliation Records description: >- Operations to retrieve reconciliation record aggregates, transactions, and reconciliation metadata. - name: Report Runs description: Operations to generate and retrieve report runs. - name: Reports description: Operations to see available reports. - name: Rulesets description: Operations related to managing Rulesets. - name: SSO Connections description: Operations related to managing SSO identity provider connections. - name: Vault Display SDK description: Operations related to DisplaySDK. - name: Vault Instant Proxy description: Operations related to Instant Proxy API requests. - name: Vault Proxy Connections description: Operations related to managing token connections. - name: Vault Public Encryption description: Public endpoints related to encryption. - name: Vault Records and Aliases description: Operations related to managing records and aliases. - name: Workflows description: >- Any operation in Payrails is defined and executed with a [Workflow](/guides/whats-payrails/workflow/) that is configured for a particular use-case of the merchant. The workflow configurations support versioning. - name: Workspaces description: Operations related to managing workspaces. paths: /records/tokenize: post: tags: - Vault Records and Aliases summary: Tokenize records description: > 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. operationId: tokenizeRecords requestBody: description: Records to tokenize. required: true content: application/json: schema: type: object title: Tokenization request required: - records properties: records: type: array description: >- 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. minItems: 1 maxItems: 50 items: type: object title: Record to tokenize required: - type - fields properties: type: type: string description: Type of the record to create. enum: - card - networkToken example: card fields: type: object description: > 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. additionalProperties: type: object title: Field value required: - value properties: value: type: string description: The value to tokenize. example: cardNumber: value: '4111111111111111' expiryMonth: value: '07' expiryYear: value: '29' holderName: value: Max Mustermann securityCode: value: '111' example: 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 responses: '200': description: Tokenization completed. Check per-item errors in the response. content: application/json: schema: type: object title: Tokenization response required: - records properties: records: type: array description: > 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. items: title: Tokenization result description: > Result for a single requested record. It carries either the stored record or `error`, never both. The representation of a stored record matches the one returned by the record retrieval endpoints. allOf: - type: object title: Record object properties: id: type: string format: uuid description: Payrails unique identifier of the record. type: type: string description: >- Type of this record, e.g. `card` or `networkToken`. fingerprint: type: string description: >- The fingerprint of the record. Depending on type can be used to match with other records. fields: description: Fields belong to this record. type: array items: type: object title: Field object properties: alias: type: string description: >- Merchant-facing unique alias for the field. Used as an identifier. recordId: type: string description: >- Identifier of the record to which the alias belongs. recordType: type: string description: >- Record type to which this field belongs, e.g. `card` and `networkToken`. fieldType: type: string description: > Field type of the alias, e.g. `cardNumber`, `expiryMonth`, `expiryYear`, `securityCode`, `holderName`, `networkToken`, `cryptogram`. displayableValue: type: string nullable: true description: Displayable value for the field. allowedDetokenizationCount: type: integer nullable: true title: Allowed detokenization count. description: >- It will be restricted if used on a proxy and reaches the limit mentioned in this field. example: 0 allowedSdkRevealCount: type: integer nullable: true title: Allowed reveal count. description: >- It will be restricted if used on a SDK reveal and reaches the limit mentioned in this field. example: 0 hasValue: type: boolean nullable: true title: Whether volatile field has value. description: >- 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. maximumExpirationDate: type: string nullable: true format: date-time title: >- Maximum expiration date for volatile field. description: >- 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' detokenizations: type: array nullable: true title: Detokenization attempts. description: >- List of detokenization attempts performed on this field. This field is returned only when requested via `includeDetokenizations` query parameter. items: type: object properties: lastAttemptedAt: type: string format: date-time description: >- Timestamp when the detokenization was attempted. example: '2024-01-01T12:00:00Z' count: type: integer description: >- Number of times this type of detokenization was successfully performed. example: 1 type: type: string description: >- Type of detokenization attempt. `detokenization` indicates a standard detokenization, while `sdkReveal` indicates a detokenization performed via SDK reveal. example: detokenization enum: - detokenization - sdkReveal - type: object properties: error: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: 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 '400': description: Bad Request. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: 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 '401': description: Unauthorized. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: 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 '403': description: Insufficient Scope. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: 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 '404': description: Not Found. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: 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 '413': description: Content Too Large. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: 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 '422': description: Unprocessable Entity. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: 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 '503': description: Service Unavailable Error. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: 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 security: - BearerVaultToken: - vaultrecords:tokenize servers: - url: https://api.vault.payrails.io description: >- Payrails Vault host. This endpoint is not served on the Payrails API host. components: securitySchemes: ApiKey: type: apiKey in: header name: x-api-key description: > You can use your secret API key in the `x-api-key` header of your API requests for supported endpoints: `x-api-key: `. API keys are environment specific and should be securely guarded. You don't have your API key yet? Contact your Payrails account manager. BearerVaultToken: type: http scheme: bearer bearerFormat: JWT description: > You can use an OAuth2 JWT bearer token in the `Authorization` header of your API requests for supported endpoints: `Authorization: Bearer `. These tokens are short-lived (the exact lifetime is returned in `expires_in`) and can be requested via the [vault access token](#operation/getVaultAccessToken) endpoint. They are accepted only on the Payrails Vault host and grant access to the tokenization and detokenization endpoints. ```` ## Related topics - [Direct Vault API](/docs/token-vault/direct-vault-api.md) - [Records, Aliases and Instruments](/docs/token-vault/tokenize-records.md) - [Getting started](/reference/index.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.