{ "openapi": "3.0.0", "info": { "title": "Card Token Vault API", "description": "The Card Token Vault API allows VTEX merchants to manage card tokens, including creation, updates, retrieval, deletion, and bulk imports. Card tokens are unique identifiers that represent securely stored credit card data.\r\n\r\n> ⚠️ This feature is in closed beta, meaning only specific customers can access it now. If you want to implement it in the future, please contact [our Support](https://support.vtex.com/hc/en-us/).\r\n\r\n>ℹ️ The endpoints of this API can be used for personal cards (cards associated with a single buyer) and shared cards (cards used by more than one person and associated with a specific contract). However, in a scenario of operations with personal cards, the `shopperId` must be additionally sent on the **Created card token** or **Updated card token** endpoints.", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{accountName}.vtexcommercestable.com.br", "description": "VTEX server URL.", "variables": { "accountName": { "description": "Name of the VTEX account. Used as part of the URL.", "default": "apiexamples" } } } ], "paths": { "/api/card-token-vault/tokens": { "post": { "tags": [ "Card token" ], "summary": "Create card token", "description": "Registers a new card token in the Card Token Vault (CTV).\r\n\r\n> ⚠️ This feature is in closed beta, meaning only specific customers can access it now. If you want to implement it in the future, please contact [our Support](https://support.vtex.com/hc/en-us/).\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Payments | Card Token Vault | **Create Card Tokens** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "CreateCardToken", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardTokenRequest" } } } }, "responses": { "201": { "description": "Created - Token saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardToken" }, "example": { "id": "EAA2FC55554448D7B56DE57D9ACDE1B1", "accountName": "apiexamples", "providerId": "brpay", "orderGroup": "v71021570str", "profileId": "profile-id", "shopperId": "shopper-id", "email": "shopper@example.com", "card": { "paymentSystemId": "123", "paymentSystemName": "Visa", "firstDigits": "000000", "lastDigits": "0000", "address": { "addressType": "Residential", "addressId": "address-123", "postalCode": "00000-000", "street": "St. Example", "neighborhood": "Centro", "city": "Example City", "state": "SP", "country": "BRA", "number": "1000", "complement": "Apt 1" }, "holderName": "Shopper Example" }, "cardTokenData": { "type": "TOKEN_VALUE", "value": "token-value", "expiration": "2025-12", "label": "Primary card", "providerCardTokenId": "provider-token-id", "useCvvForAuthorization": false, "href": "https://provider.example/token-file" }, "extraData": { "additionalProp1": "custom-value" } } } } }, "400": { "description": "Bad Request - Problem validating request data." }, "401": { "description": "Unauthorized - Invalid or unauthorized auth headers." }, "403": { "description": "Forbidden - Missing auth headers." }, "409": { "description": "Conflict - Token already exists." }, "500": { "description": "Internal Server Error - Unexpected issue on the server. Retry after a short delay or contact support if the problem persists." } } } }, "/api/card-token-vault/tokens/{id}": { "put": { "tags": [ "Card token" ], "summary": "Update card token", "description": "Updates data for an existing token in the Card Token Vault (CTV).\r\n\r\n> ⚠️ This feature is in closed beta, meaning only specific customers can access it now. If you want to implement it in the future, please contact [our Support](https://support.vtex.com/hc/en-us/).\r\n\r\nThis endpoint requires sending the complete request body from the **Create Card Token** endpoint, except for the `card` object.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Payments | Card Token Vault | **Edit Card Tokens** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "UpdateCardToken", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/CardTokenId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCardTokenRequest" } } } }, "responses": { "201": { "description": "Created - Token saved." }, "400": { "description": "Bad Request - Problem validating request data." }, "401": { "description": "Unauthorized - Invalid or unauthorized auth headers." }, "403": { "description": "Forbidden - Missing auth headers." }, "404": { "description": "Not Found - Token not previously registered." }, "500": { "description": "Internal Server Error - Unexpected issue on the server. Retry after a short delay or contact support if the problem persists." } } } }, "/api/payments/pvt/accounts/{id}": { "get": { "tags": [ "Card token" ], "summary": "Get card token by ID", "description": "Retrieves data for a specific token by its ID (unique identifier automatically generated during token creation).\r\n\r\n> ⚠️ This feature is in closed beta, meaning only specific customers can access it now. If you want to implement it in the future, please contact [our Support](https://support.vtex.com/hc/en-us/).\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| PCI Gateway | Payment-ViewPaymentData | **View Payment Data** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetCardTokenById", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/CardTokenId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardToken" }, "example": { "id": "EAA2FC55554448D7B56DE57D9ACDE1B1", "accountName": "apiexamples", "providerId": "brpay", "orderGroup": "v71021570str", "profileId": "profile-id", "shopperId": "shopper-id", "email": "shopper@example.com", "card": { "paymentSystemId": "123", "paymentSystemName": "Visa", "firstDigits": "000000", "lastDigits": "0000", "address": { "addressType": "Residential", "addressId": "address-id", "postalCode": "00000-000", "street": "Av. Example", "neighborhood": "Centro", "city": "Example City", "state": "SP", "country": "BRA", "number": "1000", "complement": "Apt 1" }, "holderName": "Shopper Example" }, "cardTokenData": { "type": "TOKEN_VALUE", "value": "token-value", "expiration": "2025-12", "label": "Primary card", "providerCardTokenId": "provider-token-id", "useCvvForAuthorization": false, "href": "https://provider.example/token-file" }, "extraData": { "additionalProp1": "string" } } } } }, "400": { "description": "Bad Request - Invalid request data." }, "401": { "description": "Unauthorized - Invalid or unauthorized auth headers." }, "403": { "description": "Forbidden - Missing auth headers." }, "404": { "description": "Not Found - Token not previously registered." }, "500": { "description": "Internal Server Error - Unexpected issue on the server. Retry after a short delay or contact support if the problem persists." } } }, "delete": { "tags": [ "Card token" ], "summary": "Delete card token", "description": "Deletes a card token in the Card Token Vault (CTV).\r\n\r\n> ⚠️ This feature is in closed beta, meaning only specific customers can access it now. If you want to implement it in the future, please contact [our Support](https://support.vtex.com/hc/en-us/).\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| PCI Gateway | Payment-MakePayments| **Process payments** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "DeleteCardToken", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/CardTokenId" } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized - Invalid or unauthorized auth headers." }, "403": { "description": "Forbidden - Missing auth headers." }, "404": { "description": "Not Found - Token not previously registered." }, "500": { "description": "Internal Server Error - Unexpected issue on the server. Retry after a short delay or contact support if the problem persists." } } } }, "/api/card-token-vault/tokens/import": { "post": { "tags": [ "Card token import" ], "summary": "Import card tokens", "description": "Imports tokens in bulk using an XLSX file.\r\n\r\n> ⚠️ This feature is in closed beta, meaning only specific customers can access it now. If you want to implement it in the future, please contact [our Support](https://support.vtex.com/hc/en-us/).\r\n\r\nBefore starting an import process, it's important to consider the following requirements and behavioral rules:\r\n- **File requirements:** Only `.xlsx` files up to **20 MB** are supported.\r\n- **Simultaneous imports:** Each account can trigger only **one import operation at a time**. If an import is already in progress, you must wait for it to finish before starting a new one.\r\n- **Auditing:** All import operations are **fully audited** for traceability.\r\n\r\nThe request body must include your XLSX file, provided as a form-data part. The first row of the file must contain the following headers:\r\n\r\n| `accountName` | `providerId` | `profileId` | `paymentSystemName` | `cardFirstDigits` | `cardLastDigits` | `cardAddressType` | `cardAddressPostalCode` | `cardAddressStreet` | `cardAddressNeighborhood` | `cardAddressCity` | `cardAddressState` | `cardAddressCountry` | `cardAddressNumber` | `cardAddressComplement` | `cardHolderName` | `tokenType` | `tokenValue` | `tokenExpiration` | `tokenLabel` | `tokenProviderCardTokenId` | `tokenUseCvvForAuthorization` | `tokenHref` | `extraData` | `email` | `shopperId` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Payments | Card Token Vault | **Import Card Token** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "ImportCardTokens", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "multipart/form-data" } }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "XLSX file with the card tokens to import.", "example": "tokens.xlsx" } } } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCardTokensResponse" }, "example": { "id": "import-123" } } } }, "400": { "description": "Bad Request - Incorrect `Content-Type` or invalid file." }, "401": { "description": "Unauthorized - Invalid or unauthorized auth headers." }, "403": { "description": "Forbidden - Missing auth headers." }, "500": { "description": "Internal Server Error - Unexpected issue on the server. Retry after a short delay or contact support if the problem persists." } } } }, "/api/card-token-vault/tokens/import/{importId}": { "get": { "tags": [ "Card token import" ], "summary": "Get card token import status", "description": "Returns the status and progress percentage of an import.\r\n\r\n> ⚠️ This feature is in closed beta, meaning only specific customers can access it now. If you want to implement it in the future, please contact [our Support](https://support.vtex.com/hc/en-us/).\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Payments | Card Token Vault | **Get Import Card Token Status** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetCardTokenImportStatus", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/ImportId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportStatus" }, "example": { "status": "RUNNING", "id": "import-123", "completionPercentage": 42, "createdDate": "2024-01-15T12:00:00Z", "updatedDate": "2024-01-15T12:05:00Z", "reportUrl": "https://example.vtexcommercestable.com.br/api/card-token-vault/tokens/import/import-123/report" } } } }, "401": { "description": "Unauthorized - Invalid or unauthorized auth headers." }, "403": { "description": "Forbidden - Missing auth headers." }, "404": { "description": "Not Found - Import not found." }, "500": { "description": "Internal Server Error - Unexpected issue on the server. Retry after a short delay or contact support if the problem persists." } } } }, "/api/card-token-vault/tokens/import/{importId}/report": { "get": { "tags": [ "Card token import" ], "summary": "Get card token import report", "description": "Returns the import report, indicating lines with issues.\r\n\r\n> ⚠️ This feature is in closed beta, meaning only specific customers can access it now. If you want to implement it in the future, please contact [our Support](https://support.vtex.com/hc/en-us/).\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Payments | Card Token Vault | **Get Import Card Tokens Report** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetCardTokenImportReport", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/ImportId" } ], "responses": { "302": { "description": "Found" }, "401": { "description": "Unauthorized - Invalid or unauthorized auth headers." }, "403": { "description": "Forbidden - Missing auth headers." }, "404": { "description": "Not Found - Import not found." }, "500": { "description": "Internal Server Error - Unexpected issue on the server. Retry after a short delay or contact support if the problem persists." } } } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ], "components": { "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey", "description": "Unique identifier of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken", "description": "Secret token of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "VtexIdclientAutCookie": { "type": "apiKey", "in": "header", "name": "VtexIdclientAutCookie", "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours." } }, "schemas": { "CardTokenAddress": { "type": "object", "description": "Billing address associated with the card token.", "properties": { "addressType": { "type": "string", "description": "Address type. Example: `Residential`." }, "addressId": { "type": "string", "description": "Unique identifier for the address." }, "postalCode": { "type": "string", "description": "Postal code (ZIP/CEP)." }, "street": { "type": "string", "description": "Street name." }, "neighborhood": { "type": "string", "description": "Neighborhood name." }, "city": { "type": "string", "description": "City name." }, "state": { "type": "string", "description": "State or province." }, "country": { "type": "string", "description": "Billing address country code (ISO 3166 alpha-3)." }, "number": { "type": "string", "description": "Street number." }, "complement": { "type": "string", "description": "Address complement (e.g., apartment, building)." } } }, "CardTokenCard": { "type": "object", "description": "Card information persisted with the token.", "required": [ "paymentSystemName", "firstDigits", "lastDigits" ], "properties": { "paymentSystemId": { "type": "string", "description": "Payment system ID in the Payment Gateway." }, "paymentSystemName": { "type": "string", "description": "Payment system name (card brand)." }, "firstDigits": { "type": "string", "description": "First six digits (BIN) of the card." }, "lastDigits": { "type": "string", "description": "Last four digits of the card." }, "address": { "$ref": "#/components/schemas/CardTokenAddress" }, "holderName": { "type": "string", "description": "Name of the cardholder as printed on the card." } } }, "CardTokenDataResponse": { "type": "object", "description": "Token-specific metadata used by the card token vault.", "required": [ "type", "expiration" ], "properties": { "type": { "type": "string", "description": "Token type stored in the vault.", "enum": [ "FILE", "TOKEN_CLIENT_ID", "TOKEN_VALUE" ] }, "value": { "type": "string", "description": "Token value to be used in transactions. Required when `type` is TOKEN_VALUE." }, "expiration": { "type": "string", "description": "Token expiration date in `YYYY-MM` format." }, "label": { "type": "string", "description": "Token alias (an alternative name to simplify token identification)." }, "providerCardTokenId": { "type": "string", "description": "Client ID used to retrieve the token from the provider. This field is required if the `type` is TOKEN_CLIENT_ID." }, "useCvvForAuthorization": { "type": "boolean", "default": false, "description": "Flag indicating if CVV is required (`true`) or not (`false`)." }, "href": { "type": "string", "description": "URL of the token file stored by the provider. This field is required if the `type` is FILE." } } }, "CardTokenAddressInput": { "type": "object", "description": "Card address object.", "properties": { "addressType": { "type": "string", "description": "Address type. Example: `Residential`.", "example": "Residential" }, "addressId": { "type": "string", "description": "Unique identifier for the address.", "example": "address-123" }, "postalCode": { "type": "string", "description": "Postal code (ZIP/CEP).", "example": "00000-000" }, "street": { "type": "string", "description": "Street name.", "example": "St. Example" }, "neighborhood": { "type": "string", "description": "Neighborhood name.", "example": "Centro" }, "city": { "type": "string", "description": "City name.", "example": "Example City" }, "state": { "type": "string", "description": "State or province.", "example": "SP" }, "country": { "type": "string", "description": "Billing address country code (ISO 3166 alpha-3).", "example": "BRA" }, "number": { "type": "string", "description": "Street number.", "example": "1000" }, "complement": { "type": "string", "description": "Address complement (e.g., apartment, building).", "example": "Apt 1" } } }, "CardTokenCardInput": { "type": "object", "description": "Card information sent when creating or updating a token.", "required": [ "paymentSystemName", "firstDigits", "lastDigits" ], "properties": { "paymentSystemId": { "type": "string", "description": "Payment system ID in the Payment Gateway.", "example": "123" }, "paymentSystemName": { "type": "string", "description": "Payment system name (card brand).", "example": "Visa" }, "firstDigits": { "type": "string", "description": "First six digits (BIN) of the card.", "example": "000000" }, "lastDigits": { "type": "string", "description": "Last four digits of the card.", "example": "0000" }, "address": { "$ref": "#/components/schemas/CardTokenAddressInput" }, "holderName": { "type": "string", "description": "Name of the cardholder as printed on the card.", "example": "Shopper Example" } } }, "CardTokenData": { "type": "object", "description": "Token metadata sent when creating or updating a token.", "required": [ "type", "expiration" ], "properties": { "type": { "type": "string", "description": "Token type stored in the vault.", "enum": [ "FILE", "TOKEN_CLIENT_ID", "TOKEN_VALUE" ], "example": "TOKEN_VALUE" }, "value": { "type": "string", "description": "The token value to be used in transactions. This field is required if the `type` is TOKEN_VALUE.", "example": "token-value" }, "expiration": { "type": "string", "description": "Token expiration date in `YYYY-MM` format.", "example": "2025-12" }, "label": { "type": "string", "description": "Token alias (an alternative name to simplify token identification).", "example": "Primary card" }, "providerCardTokenId": { "type": "string", "description": "Client ID used to retrieve the token from the provider. This field is required if the `type` is TOKEN_CLIENT_ID.", "example": "provider-token-id" }, "useCvvForAuthorization": { "type": "boolean", "description": "Flag indicating if CVV is required (`true`) or not (`false`).", "example": false }, "href": { "type": "string", "description": "URL of the token file stored by the provider. This field is required if the `type` is FILE.", "example": "https://provider.example/token-file" } } }, "CardToken": { "type": "object", "description": "Card token payload returned by the API.", "properties": { "id": { "type": "string", "description": "Token ID (unique identifier automatically generated during token creation and stored in the system)." }, "accountName": { "type": "string", "description": "Name of the VTEX account that owns the token." }, "providerId": { "type": "string", "description": "Name of the payment provider responsible for the tokenized card." }, "orderGroup": { "type": "string", "description": "Order group ID, a segment of the order ID that groups all orders related to the same purchase. For example, in the order ID `v71021570str-02`, the order group ID is `v71021570str`." }, "profileId": { "type": "string", "description": "Profile ID in the Profile System (used for contract identification)." }, "shopperId": { "type": "string", "description": "Shopper identification." }, "email": { "type": "string", "description": "Email is used only if neither `profileId` nor `orderGroup` are provided." }, "card": { "$ref": "#/components/schemas/CardTokenCard" }, "cardTokenData": { "$ref": "#/components/schemas/CardTokenDataResponse" }, "extraData": { "type": "object", "description": "Additional metadata stored with the token.", "additionalProperties": { "type": "string", "description": "Additional metadata value." } } }, "required": [ "id", "providerId", "cardTokenData" ] }, "CreateCardTokenRequest": { "type": "object", "description": "Payload sent to create a new card token.", "required": [ "providerId", "card", "cardTokenData" ], "properties": { "providerId": { "type": "string", "description": "Name of the payment provider responsible for the tokenized card.", "example": "brpay" }, "profileId": { "type": "string", "description": "Profile ID in the Profile System (used for contract identification). This field is optional if `email` or `orderGroup` exists.", "example": "profile-id" }, "shopperId": { "type": "string", "description": "Shopper identification. This field is optional and only applicable if a personal card is used.", "example": "shopper-id" }, "email": { "type": "string", "description": "Email is used only if neither `profileId` nor `orderGroup` are provided.", "example": "shopper@example.com" }, "orderGroup": { "type": "string", "description": "Order group ID, a segment of the order ID that groups all orders related to the same purchase. For example, in the order ID `v71021570str-02`, the order group ID is `v71021570str`. This field is optional if `email` or `profileId` exists.", "example": "v71021570str" }, "card": { "$ref": "#/components/schemas/CardTokenCardInput" }, "cardTokenData": { "$ref": "#/components/schemas/CardTokenData" }, "extraData": { "type": "object", "description": "Additional key/value pairs to persist with the token.", "additionalProperties": { "type": "string", "description": "Additional metadata value.", "example": "custom-value" } } } }, "UpdateCardTokenRequest": { "type": "object", "description": "Payload sent to update an existing card token.", "properties": { "providerId": { "type": "string", "description": "Name of the payment provider responsible for the tokenized card.", "example": "brpay" }, "profileId": { "type": "string", "description": "Profile ID in the Profile System (used for contract identification). This field is optional if `email` or `orderGroup` exists.", "example": "profile-id" }, "shopperId": { "type": "string", "description": "Shopper identification. This field is optional and only applicable if a personal card is used.", "example": "shopper-id" }, "email": { "type": "string", "description": "Email is used only if neither profileId nor orderGroup are provided.", "example": "shopper@example.com" }, "orderGroup": { "type": "string", "description": "Order group ID, a segment of the order ID that groups all orders related to the same purchase. For example, in the order ID `v71021570str-02`, the order group ID is `v71021570str`. This field is optional if `email` or `profileId` exists.", "example": "v71021570str" }, "cardTokenData": { "$ref": "#/components/schemas/CardTokenData" }, "extraData": { "type": "object", "description": "Additional key/value pairs to persist with the token.", "additionalProperties": { "type": "string", "description": "Additional metadata value.", "example": "custom-value" }, "example": { "additionalProp1": "custom-value" } } }, "required": [ "providerId", "cardTokenData" ] }, "ImportCardTokensResponse": { "type": "object", "description": "Response payload returned after a card token import submission.", "properties": { "id": { "type": "string", "description": "Import ID." } } }, "ImportStatus": { "type": "object", "description": "Status details for a submitted card token import.", "properties": { "status": { "type": "string", "description": "Import status value.", "enum": [ "DONE", "RUNNING", "CREATED", "FAILED" ] }, "id": { "type": "string", "description": "Import ID." }, "completionPercentage": { "type": "integer", "description": "Importing completion percentage." }, "createdDate": { "type": "string", "description": "Creation date." }, "updatedDate": { "type": "string", "description": "Last update date." }, "reportUrl": { "type": "string", "description": "Report URL. This field is optional if the import process had an error." } } } }, "parameters": { "Content-Type": { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, "Accept": { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, "CardTokenId": { "name": "id", "in": "path", "description": "Token ID (unique identifier automatically generated during token creation and stored in the system).", "required": true, "schema": { "type": "string" } }, "ImportId": { "name": "importId", "in": "path", "description": "Import ID.", "required": true, "schema": { "type": "string" } } } }, "tags": [ { "name": "Card token" }, { "name": "Card token import" } ] }