{ "openapi": "3.0.0", "info": { "title": "Anti-fraud Provider API", "description": ">ℹ️ Check the [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview) for a journey-based overview of the Payments documentation available in the Developer Portal.\r\n\r\nThe Anti-fraud Provider Protocol is a set of definitions to help you integrate your anti-fraud service API into VTEX platform.\r\n\r\nTo achieve this, you need to implement a web API (REST) following the specifications described in this documentation.\r\n\r\n>⚠️ You can also access our [template on GitHub](https://github.com/vtex-apps/antifraud-provider-example) to help you quickly develop your anti-fraud connector using the Anti-fraud Provider Protocol and VTEX IO.\r\n\r\nTo learn more about the Anti-fraud Provider Protocol, check our [developer guide](https://developers.vtex.com/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works).", "version": "1.0" }, "servers": [ { "url": "https://{providerApiEndpoint}", "description": "Anti-fraud provider endpoint URL.", "variables": { "providerApiEndpoint": { "description": "Anti-fraud provider endpoint URL.", "default": "{providerApiEndpoint}" } } } ], "paths": { "/pre-analysis": { "post": { "tags": [ "Anti-fraud Flow" ], "summary": "Send anti-fraud pre-analysis data (optional)", "description": "Receives a new transaction anti-fraud data for (synchronous) pre-analysis. This step is performed before payments authorization.\r\n\r\n>⚠️ This endpoint can only be used if your anti-fraud provider already has the pre-analysis function configured within VTEX. To check if it is already configured, in the VTEX Admin, go to **Store Settings > Payment > Providers**, click the name of your anti-fraud provider, and verify if the **Enable Risk Pre-Analysis** field is available to be selected. If the **Enable Risk Pre-Analysis** field is not available, check with your anti-fraud provider if this feature is available in their integration and open a ticket in our [VTEX Support](https://help.vtex.com/en/support) to update the connector.\r\n\r\n>⚠️ The pre-analysis does not exclude the need for full analysis after payments authorization.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "operationId": "SendAntifraudPreAnalysisData", "parameters": [ { "$ref": "#/components/parameters/X-PROVIDER-API-AppKey" }, { "$ref": "#/components/parameters/X-PROVIDER-API-AppToken" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "security": [ { "VtexIdclientAutCookie": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendAntifraudDataRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendAntifraudData" }, "example": { "id": "D3AA1FC8372E430E8236649DB5EBD08E", "tid": "4692c1f54d514fe69da0b472a3b2a770", "code": "customCode", "message": "customMessage", "status": "approved", "score": 5.01, "analysisType": "automatic", "responses": { "foo": "anyFoo", "custom": "customAnyValue" } } } } } } } }, "/transactions": { "post": { "tags": [ "Anti-fraud Flow" ], "summary": "Send anti-fraud data", "description": "Receives a new transaction anti-fraud data. This step is performed only if all payments are authorized.\r\n\r\nVTEX expects that your anti-fraud provider process this request and retrieves the process result. After that, the VTEX order flow will check the response status to cancel or approve the transaction.\n\r\n\r> Only data from the main account is sent from VTEX to the anti-fraud system. Information related to subaccounts is not included in the request.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "operationId": "SendAntifraudData", "parameters": [ { "$ref": "#/components/parameters/X-PROVIDER-API-AppKey" }, { "$ref": "#/components/parameters/X-PROVIDER-API-AppToken" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "security": [ { "VtexIdclientAutCookie": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendAntifraudDataRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendAntifraudData" }, "example": { "id": "D3AA1FC8372E430E8236649DB5EBD08E", "tid": "4692c1f54d514fe69da0b472a3b2a770", "code": "customCode", "message": "customMessage", "status": "approved", "score": 5.01, "analysisType": "automatic", "responses": { "foo": "anyFoo", "custom": "customAnyValue" } } } } } } } }, "/transactions/{transactionId}": { "put": { "tags": [ "Anti-fraud Flow" ], "summary": "Update anti-fraud transactions (optional)", "description": "Receives a new transaction anti-fraud data. This step is performed only if all payments are authorized.\r\n\r\nVTEX expects that your anti-fraud provider process this request and retrieves the process result. After that, the VTEX order flow will check the response status to cancel or approve the transaction.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "operationId": "UpdateAntifraudTransactions(optional)", "parameters": [ { "$ref": "#/components/parameters/X-PROVIDER-API-AppKey" }, { "$ref": "#/components/parameters/X-PROVIDER-API-AppToken" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/transactions.Id" } ], "security": [ { "VtexIdclientAutCookie": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAntifraudTransactionsoptionalRequest" }, "example": { "id": "D3AA1FC8372E430E8236649DB5EBD08E", "reference": "v32478982vtx-01", "value": 10, "ip": "10.0.0.1", "store": "serasa", "deviceFingerprint": "Generated_using_GTM_Store_Is_Responsible_To_Configure", "miniCart": { "buyer": { "id": "c1245228-1c68-11e6-94ac-0afa86a846a5", "firstName": "John", "lastName": "Doe", "document": "012.345.678-90", "documentType": "CPF", "email": "john@doe.com", "phone": "+5521987654321", "address": { "country": "BRA", "street": "Rua Praia de Botafogo", "number": "518", "complement": "2o. andar", "neighborhood": "Botafogo", "postalCode": "22250-040", "city": "Rio de Janeiro", "state": "RJ" } }, "shipping": { "value": 8.41, "estimatedDate": "2017-08-02T14:46:47", "address": { "country": "BRA", "street": "Rua Praia de Botafogo", "number": "518", "complement": "2o. andar", "neighborhood": "Botafogo", "postalCode": "22250-040", "city": "Rio de Janeiro", "state": "RJ" } }, "items": [ { "id": "132981", "name": "Some useful product", "price": 20.51, "quantity": 2, "deliveryType": "Normal", "deliverySlaInMinutes": 4320, "categoryId": "111", "categoryName": "Electronica", "discount": 1.99, "sellerId": "vtexargentina" }, { "id": "123242", "name": "Some useless product", "price": 21.98, "quantity": 1, "deliveryType": "Normal", "deliverySlaInMinutes": 4320, "categoryId": "123", "categoryName": "Lar", "discount": 1.01, "sellerId": "vtexargentina" } ], "taxValue": 5.58, "listRegistry": { "name": "Minha lista Presente", "deliveryToOwner": false } }, "payments": [ { "id": "2D00FE", "method": "CreditCard", "name": "Visa", "value": 63.98, "currencyIso4217": "BRL", "installments": 3, "details": { "bin": "507860", "lastDigits": "2798", "holder": "John Doe", "address": { "country": "BRA", "street": "Rua Praia de Botafogo", "number": "518", "complement": "2o. andar", "neighborhood": "Botafogo", "postalCode": "22250-040", "city": "Rio de Janeiro", "state": "RJ" } } }, { "id": "04D430E517B2494FBC3DF7721CCDACC7", "method": "GiftCard", "value": 10.01, "currencyIso4217": "BRL", "installments": 1 } ], "hook": "https://hook.vtex.com/notifyIfChangeStatus" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveAntifraudAnalysisResponse" }, "example": { "id": "D3AA1FC8372E430E8236649DB5EBD08E", "status": "approved", "fraudRiskPercentage": 0.0, "analysisType": "automatic", "responses": null } } } } } } }, "/manifest": { "get": { "tags": [ "Anti-fraud Flow" ], "summary": "List anti-fraud provider manifest", "description": "Returns the custom fields of the anti-fraud provider manifest.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https:\/\/developers.vtex.com\/docs\/guides\/authentication) or [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "operationId": "Manifest", "security": [], "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" }, "example": { "cardholderDocument": "required", "allowAntifraudOnGiftCard": true, "customFields": [ { "name": "AnalysisMode", "type": "text" }, { "name": "Client secret", "type": "password" }, { "name": "AnalysisLocation", "type": "select", "options": [ { "text": "MEX", "value": "Latin America" }, { "text": "USA", "value": "United States" } ] } ] } } } } } } }, "/transactions/{transactions.id}": { "get": { "tags": [ "Anti-fraud Flow" ], "summary": "Get anti-fraud status", "description": "Retrieves the anti-fraud analysis status. This request is performed every two hours up to 5 days. After 5 days in `undefined` status, the order will expire and be cancelled.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "operationId": "GetAntifraudStatus", "parameters": [ { "$ref": "#/components/parameters/X-PROVIDER-API-AppKey" }, { "$ref": "#/components/parameters/X-PROVIDER-API-AppToken" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/transactions.Id" } ], "security": [ { "VtexIdclientAutCookie": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAntifraudStatus" }, "example": { "id": "BF900B7CB15147F98D91208989100A05", "tid": "3146f46162f042f483cd3979ba4e8317", "status": "approved", "fraudRiskPercentage": 5.01, "analysisType": "automatic", "responses": { "foo": "anyFoo", "custom": "customAnyValue" } } } } } } } }, "/transactions/{transactions.Id}": { "delete": { "tags": [ "Anti-fraud Flow" ], "summary": "Stop anti-fraud analysis (optional)", "description": "Notifies whether the order has been canceled by the store or the buyer before completing the anti-fraud analysis status.\r\n\r\n This endpoint is not mandatory for the antifraud flow to work. Check this [developer guide](https://developers.vtex.com/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works) for more details.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "operationId": "StopAntifraudAnalysis(optional)", "parameters": [ { "$ref": "#/components/parameters/X-PROVIDER-API-AppKey" }, { "$ref": "#/components/parameters/X-PROVIDER-API-AppToken" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/transactions.Id" } ], "security": [ { "VtexIdclientAutCookie": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetPaymentMethodsSupported" } }, "example": [ { "name": "CreditCard" }, { "name": "DebitCard" }, { "name": "GiftCard" }, { "name": "BankIssueInvoice" }, { "name": "Voucher" }, { "name": "Promissory" } ] } } } } } }, "/authorization/token": { "post": { "tags": [ "OAuth Flow" ], "summary": "1. Retrieve token", "description": "This endpoint is used to retrieve a payment provider token.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "operationId": "1.RetrieveToken", "parameters": [ { "$ref": "#/components/parameters/X-PROVIDER-API-AppKey" }, { "$ref": "#/components/parameters/X-PROVIDER-API-AppToken" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "security": [ { "VtexIdclientAutCookie": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/1.RetrieveTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/1.RetrieveToken" }, "example": { "applicationId": "vtex", "token": "358a5bea-07d0-4122-888a-54ab70b5f02f" } } } } } } }, "/redirect": { "get": { "tags": [ "OAuth Flow" ], "summary": "2. Redirect", "description": "Through this endpoint, VTEX will redirect the store administrator to the Payment provider website using the `token` retrieved in the [previous request](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/authorization/token).\r\n\r\nAt this point in the flow, the provider shows the login site to the store admin and authorizes VTEX to use its integration as a valid Payment Provider Processor. After that, your server generates an `authorizationCode`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "operationId": "2.Redirect", "parameters": [ { "name": "token", "in": "query", "description": "Token information.", "required": true, "style": "form", "schema": { "type": "string", "example": "{token}" } }, { "name": "applicationId", "in": "query", "description": "VTEX application identifier.", "required": true, "style": "form", "schema": { "type": "string", "example": "vtex" } }, { "$ref": "#/components/parameters/X-PROVIDER-API-AppKey" }, { "$ref": "#/components/parameters/X-PROVIDER-API-AppToken" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "security": [ { "VtexIdclientAutCookie": [] } ], "responses": { "200": { "description": "OK. This endpoint does not return any data in the response body." } } } }, "/authorizationCode": { "get": { "tags": [ "OAuth Flow" ], "summary": "3. Return to VTEX", "description": "Through this endpoint, the provider will redirect the store administrator to the VTEX website using the `returnUrl` passed from VTEX to create token.\r\n\r\nThe `returnUrl` must be filled with your query string **authorizationCode**.\r\n\r\nExample:\r\n\r\nIf you receive the following URL:\r\n\r\n`https://store.vtex.com/return?authorizationCode=&otherparams...`\r\n\r\nand your **authorizationCode** is `pro2018`. Then, you redirect the store administrator to: `https://store.vtex.com/return?authorizationCode=pro2018&otherparams...`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "operationId": "3.ReturntoVTEX", "parameters": [ { "name": "providerAuthorizationCode", "in": "query", "description": "Provider authorization code information.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "{providerAuthorizationCode}" } }, { "$ref": "#/components/parameters/X-PROVIDER-API-AppKey" }, { "$ref": "#/components/parameters/X-PROVIDER-API-AppToken" } ], "security": [ { "VtexIdclientAutCookie": [] } ], "responses": { "200": { "description": "OK. This endpoint does not return any data in the response body." } } } }, "/authorization/credentials": { "get": { "tags": [ "OAuth Flow" ], "summary": "4. Get credentials", "description": "Retrieves merchant credentials.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "operationId": "4.GetCredentials", "parameters": [ { "name": "authorizationCode", "in": "query", "description": "Code generate by affiliation that will be used to identify the merchant authorization.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "{authorizationCode}" } }, { "name": "applicationId", "in": "query", "description": "VTEX application identifier.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "vtex" } }, { "$ref": "#/components/parameters/X-PROVIDER-API-AppKey" }, { "$ref": "#/components/parameters/X-PROVIDER-API-AppToken" } ], "security": [ { "VtexIdclientAutCookie": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/3.GetCredentials" }, "example": { "applicationId": "vtex", "appKey": "c5a5e3f1-4a77-4a00-8b53-0d1adb3e9628", "appToken": "57ea254d-f3d3-488d-88d7-129766037ed1" } } } } }, "deprecated": false } } }, "components": { "securitySchemes": { "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." } }, "parameters": { "X-PROVIDER-API-AppKey": { "name": "X-PROVIDER-API-AppKey", "in": "header", "description": "Unique identifier created by the provider and configured on the provider configuration page (Admin VTEX).", "required": true, "style": "simple", "schema": { "type": "string", "example": "{{X-PROVIDER-API-AppKey}}" } }, "X-PROVIDER-API-AppToken": { "name": "X-PROVIDER-API-AppToken", "in": "header", "description": "Unique token created by the provider and configured on the provider configuration page (Admin VTEX).", "required": true, "style": "simple", "schema": { "type": "string", "example": "{{X-PROVIDER-API-AppToken}}" } }, "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" } }, "transactions.Id": { "name": "transactions.Id", "in": "path", "description": "VTEX transaction ID. This parameter is the same `id` sent in the request body of the [Send Anti-fraud Data endpoint](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/transactions).", "required": true, "style": "simple", "schema": { "type": "string", "example": "D3AA1FC8372E430E8236649DB5EBD08E" } } }, "schemas": { "Success": { "required": [ "customFields" ], "type": "object", "description": "Custom fields information.", "properties": { "cardholderDocument":{ "type": "string", "description": "Indicates the requirement of cardholder document in card transactions. The field has three possible values: `required`, `optional`, or `unused`." }, "allowAntifraudOnGiftCard":{ "type": "boolean", "description": "Indicates whether the anti-fraud provider can process payment transactions made using [gift cards](https://developers.vtex.com/docs/guides/gift-card-integration-guide)." }, "customFields": { "type": "array", "description": "Describes the customized fields supported by the connector.", "items": { "type": "object", "description": "Custom fields information.", "properties": { "name": { "type": "string", "description": "Custom field name." }, "type": { "type": "string", "description": "Custom field type. Sensitive or security data should be defined as `password`.", "enum": ["text", "password", "select"] }, "options": { "type": "array", "description": "In case of `select` type, the possible params are `text` and `value`.", "items": { "type": "object", "description": "Custom field information.", "properties": { "text": { "type": "string", "description": "Custom field description." }, "value": { "type": "string", "description": "Custom field value." } } } } } } } } }, "SendAntifraudDataRequest": { "required": [ "id", "reference", "value", "ip", "store", "deviceFingerprint", "miniCart", "payments", "sellerId", "hook", "transactionStartDate" ], "type": "object", "description": "Anti-fraud data information.", "properties": { "id": { "type": "string", "description": "VTEX transaction ID. The ID of the transaction related with this payment.", "example": "D3AA1FC8372E430E8236649DB5EBD08E" }, "reference": { "type": "string", "description": "VTEX order reference key. The key of the order (from VTEX Orders system) related with this payment.", "example": "vtexargentina" }, "value": { "type": "integer", "description": "VTEX transaction order value.", "example": 10 }, "ip": { "type": "string", "description": "Original IP address from browser.", "example": "10.0.0.1" }, "store": { "type": "string", "description": "Store name. This is the same name used to access the store Admin via URL.", "example": "serasa" }, "deviceFingerprint": { "type": "string", "description": "Device fingerprint generated by the provider. This is generated by using Google Tag Manager that the provider implements. This field is optional, is sent only if received.", "example": "Generated_using_GTM_Store_Is_Responsible_To_Configure" }, "miniCart": { "$ref": "#/components/schemas/MiniCart" }, "payments": { "$ref": "#/components/schemas/Payment" }, "hook": { "type": "string", "description": "URL to be called when the payment status changes. For more information, see [Authorization and Callback URL](https://developers.vtex.com/docs/guides/payments-integration-purchase-flows#authorization).", "example": "https://hook.vtex.com/notifyIfChangeStatus" }, "transactionStartDate": { "type": "string", "description": "Date and time when the transaction started, in ISO 8601 format. Note: The letter 'Z', normally applicable in the ISO 8601 format, is not forwarded in this request. Example of field information sent in this endpoint: `2025-06-15T18:08:23`.", "example": "2025-06-15T18:08:23" }, "merchantSettings": { "type": "array", "description": "Custom fields (for the given Provider) which the Merchant must fill. Each element of this array is a key-value pair.", "items": { "type": "object", "description": "Items information.", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "Custom field name.", "example": "Country" }, "value": { "type": "string", "description": "Custom field name.", "example": "BRL" } } } } } }, "MiniCart": { "description": "Minicart information.", "required": [ "buyer", "shipping", "items", "taxValue", "listRegistry" ], "type": "object", "properties": { "buyer": { "$ref": "#/components/schemas/Buyer" }, "shipping": { "$ref": "#/components/schemas/Shipping" }, "items": { "type": "array", "description": "Items information.", "items": { "$ref": "#/components/schemas/Item" } }, "taxValue": { "type": "number", "description": "Total tax value.", "example": 5.58 }, "listRegistry": { "$ref": "#/components/schemas/ListRegistry" } } }, "Buyer": { "description": "Buyer information.", "required": [ "id", "firstName", "lastName", "document", "documentType", "email", "phone", "address" ], "type": "object", "properties": { "id": { "type": "string", "description": "VTEX buyer ID. The unique identifier of the buyer.", "example": "c1245228-1c68-11e6-94ac-0afa86a846a5" }, "firstName": { "type": "string", "description": "First name of the buyer.", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the buyer.", "example": "Doe" }, "document": { "type": "string", "description": "Document number of the buyer.", "example": "012.345.678-90" }, "documentType": { "type": "string", "description": "Type of document of the buyer, which depends on their country.", "example": "CPF" }, "email": { "type": "string", "description": "Email of the buyer.", "example": "john@doe.com" }, "phone": { "type": "string", "description": "Phone number of the buyer.", "example": "+5521987654321" }, "address": { "$ref": "#/components/schemas/Address" } } }, "Address": { "description": "Address information.", "required": [ "country", "street", "number", "complement", "neighborhood", "postalCode", "city", "state" ], "type": "object", "properties": { "country": { "type": "string", "description": "Buyer address country.", "example": "BRA" }, "street": { "type": "string", "description": "Buyer address street.", "example": "Rua Praia de Botafogo" }, "number": { "type": "string", "description": "Buyer address number.", "example": "518" }, "complement": { "type": "string", "description": "Buyer address complement.", "example": "2o. andar" }, "neighborhood": { "type": "string", "description": "Buyer address neighborhood.", "example": "Botafogo" }, "postalCode": { "type": "string", "description": "Buyer address postal code.", "example": "22250-040" }, "city": { "type": "string", "description": "Buyer address city.", "example": "Rio de Janeiro" }, "state": { "type": "string", "description": "Buyer address state.", "example": "RJ" } } }, "Shipping": { "description": "Shipping information.", "required": [ "value", "estimatedDate", "address" ], "type": "object", "properties": { "value": { "type": "number", "description": "Shipping value with two decimal places.", "example": 8.41 }, "estimatedDate": { "type": "string", "description": "Estimated shipping date ISO 8601.", "example": "2017-08-02T14:46:47" }, "address": { "$ref": "#/components/schemas/Address" } } }, "Item": { "description": "Item information.", "required": [ "id", "name", "price", "quantity", "deliveryType", "deliverySlaInMinutes", "categoryId", "categoryName", "discount", "sellerId" ], "type": "object", "properties": { "id": { "type": "string", "description": "SKU ID.", "example": "132981" }, "name": { "type": "string", "description": "Product name.", "example": "Shirt" }, "price": { "type": "number", "description": "Item price.", "example": 20.51 }, "quantity": { "type": "integer", "description": "Quantity of this item in the cart.", "example": 2 }, "deliveryType": { "type": "string", "description": "Type of delivery configured by the store.", "example": "Normal" }, "deliverySlaInMinutes": { "type": "integer", "description": "Each item can have a separate shipping SLA in minutes.", "example": 4320 }, "categoryId": { "type": "string", "description": "Category ID for the item. Configured by each store.", "example": "111" }, "categoryName": { "type": "string", "description": "Category name for the Item. Configured by each store.", "example": "Electronica" }, "discount": { "type": "number", "description": "Discount applied on item(s) two decimal places.", "example": 1.99 }, "sellerId": { "type": "string", "description": "Discount applied on item(s), with two decimal places separated by `.`.", "example": "vtexargentina" } } }, "ListRegistry": { "description": "ListRegistry information.", "required": [ "name", "deliveryToOwner" ], "type": "object", "properties": { "name": { "type": "string", "description": "List name defined by the store.", "example": "My gift list." }, "deliveryToOwner": { "type": "boolean", "description": "Defines if the order will be delivered to list creator (`true`) or not (`false`).", "example": false } } }, "Payment": { "description": "Payment information.", "required": [ "id", "method", "value", "currencyIso4217", "installments" ], "type": "array", "items": { "description": "Payment information.", "required": [ "id", "method", "value", "currencyIso4217", "installments" ], "type": "object", "properties": { "id": { "type": "string", "description": "Payment ID unique identifier in VTEX.", "example": "2D00FEBB" }, "method": { "type": "string", "description": "Payment method used for the buyer.", "example": "CreditCard" }, "name": { "type": "string", "description": "Payment name used for the buyer. This name could be the brand card or the VTEX payment method.", "example": "Visa" }, "value": { "type": "number", "description": "Payment value, with two decimal places separated by `.`.", "example": 63.98 }, "currencyIso4217": { "type": "string", "description": "Currency used in each payment in the transaction, in ISO 4217 format.", "example": "BRL" }, "installments": { "type": "integer", "description": "Number of installments.", "example": 3 }, "details": { "$ref": "#/components/schemas/Details" } } } }, "Details": { "description": "Details information.", "required": [ "bin", "lastDigits", "holder", "address" ], "type": "object", "properties": { "bin": { "type": "string", "description": "Abbreviation for 'Bank Identification Number', which is a code that identifies the institution responsible for issuing the credit card.", "example": "507860" }, "lastDigits": { "type": "string", "description": "Credit card identifier number last digits.", "example": "2798" }, "holder": { "type": "string", "description": "Credit card owner.", "example": "John Doe" }, "address": { "$ref": "#/components/schemas/Address" } } }, "SendAntifraudData": { "required": [ "id", "tid", "code", "message", "status", "score", "analysisType", "responses" ], "type": "object", "description": "Anti-fraud data.", "properties": { "id": { "type": "string", "description": "VTEX transaction ID. The ID of this transaction must be in the response." }, "tid": { "type": "string", "description": "Provider transaction ID. The ID of this transaction must be in the response. The anti-fraud provider must generate a unique transaction ID." }, "code": { "type": "string", "description": "Error code returned from provider. It will be logged in transaction interactions log." }, "message": { "type": "string", "description": "Error message returned from provider. It will be logged in transaction interactions log." }, "status": { "description": "Pre-analysis status from provider. Must be `approved` or `denied`.", "enum": ["approved", "denied"] }, "score": { "type": "number", "description": "Value of the risk score. The maximum value is `100.00`, which means total fraud." }, "analysisType": { "type": "string", "description": "Pre-analysis type. Must be `automatic`." }, "responses": { "$ref": "#/components/schemas/Responses" } } }, "Responses": { "required": [ "foo", "custom" ], "type": "object", "description": "Responses information.", "properties": { "foo": { "type": "string", "description": "Any foo information." }, "custom": { "type": "string", "description": "Any custom value." } } }, "UpdateAntifraudTransactionsoptionalRequest": { "required": [ "id", "reference", "value", "ip", "store", "deviceFingerprint", "miniCart", "payments", "hook" ], "type": "object", "description": "Anti-fraud transaction data.", "properties": { "id": { "type": "string", "description": "VTEX transaction ID. The ID of the transaction related with this payment.", "example": "D3AA1FC8372E430E8236649DB5EBD08E" }, "reference": { "type": "string", "description": "VTEX order reference key. The key of the order (from VTEX Orders system) related with this payment.", "example": "v32478982vtx-01" }, "value": { "type": "integer", "description": "VTEX transaction order value.", "example": 10 }, "ip": { "type": "string", "description": "The original IP address from the browser.", "example": "10.0.0.1" }, "store": { "type": "string", "description": "VTEX has a main name for the store. This unique name is often used in URL to access VTEX configurations.", "example": "serasa" }, "deviceFingerprint": { "type": "string", "description": "Device fingerprint generated by the provider. This is generated by using Google Tag Manager that the provider implements.", "example": "Generated_using_GTM_Store_Is_Responsible_To_Configure" }, "miniCart": { "$ref": "#/components/schemas/MiniCart" }, "payments": { "type": "array", "description": "Payments information.", "items": { "$ref": "#/components/schemas/Payment" } }, "hook": { "type": "string", "description": "URL to be called when the payment status changes. For more information, see [Authorization and Callback URL](https://developers.vtex.com/docs/guides/payments-integration-purchase-flows#authorization).", "example": "https://hook.vtex.com/notifyIfChangeStatus" } } }, "ApproveAntifraudAnalysisResponse": { "required": [ "id", "status", "fraudRiskPercentage", "analysisType", "responses" ], "type": "object", "description": "Anti-fraud transaction data.", "properties": { "id": { "type": "string", "description": "VTEX transaction ID. The ID of this transaction must be in the response." }, "status": { "type": "string", "description": "Transaction status from provider. Must be one of the values: `approved`, `denied` or `undefined`." }, "fraudRiskPercentage": { "type": "number", "description": "Fraud risk percentage." }, "analysisType": { "type": "string", "description": "Analysis type. Valid values are `automatic` or `manual`." }, "responses": { "type": "string", "nullable": true, "description": "Value dictionary to add custom responses from analysis." } } }, "GetAntifraudStatus": { "required": [ "id", "tid", "status", "fraudRiskPercentage", "analysisType", "responses" ], "type": "object", "description": "Anti-fraud status information.", "properties": { "id": { "type": "string", "description": "VTEX transaction ID. The ID of this transaction must be in the response." }, "tid": { "type": "string", "description": "Provider transaction ID. The ID of this transaction must be in the response. The anti-fraud provider must generate a unique transaction ID." }, "status": { "type": "string", "description": "Transaction status from provider. Must be one of the values: `approved`, `denied` or `undefined`." }, "fraudRiskPercentage": { "type": "number", "description": "Fraud risk percentage." }, "analysisType": { "type": "string", "description": "Analysis type. Valid values are `automatic` or `manual`." }, "responses": { "$ref": "#/components/schemas/Responses" } } }, "GetPaymentMethodsSupported": { "required": [ "name" ], "type": "object", "description": "Payment methods information.", "properties": { "name": { "type": "string", "description": "Payment method name." } } }, "1.RetrieveTokenRequest": { "required": [ "applicationId", "returnUrl" ], "type": "object", "description": "Token information.", "properties": { "applicationId": { "type": "string", "description": "This value is always identified as `vtex`.", "example": "vtex" }, "returnUrl": { "type": "string", "description": "VTEX website URL. You will redirect the user after they complete login on the payment provider's website. The URL should contain a query string parameter called `authorizationCode` which will be passed empty and which you must fill in before returning to the user.", "example": "https://storevtex.vtexpayments.com/?authorizationCode=" } } }, "1.RetrieveToken": { "required": [ "applicationId", "token" ], "type": "object", "description": "Token information.", "properties": { "applicationId": { "type": "string", "description": "This value is always identified as `vtex`." }, "token": { "type": "string", "description": "Payment Provider Token. Used to identify the context after you receive the redirected user to your site." } } }, "3.GetCredentials": { "required": [ "applicationId", "appKey", "appToken" ], "type": "object", "description": "Credentials information.", "properties": { "applicationId": { "type": "string", "description": "This value is always identified as `vtex`." }, "appKey": { "type": "string", "description": "It will be used in all API requests as X-VTEX-API-AppKey." }, "appToken": { "type": "string", "description": "It will be used in all API requests as X-VTEX-API-AppToken." } } } } }, "tags": [ { "name": "Anti-fraud Flow" }, { "name": "OAuth Flow" } ] }