VTEX Anti-Fraud Flow API

openapi: 3.2.0
info:
  title: VTex Anti-fraud Provider Anti-Fraud Flow API
  description: '>ℹ️ Onboarding guide

    >

    > Check the new Payments onboarding guide.'
  version: '1.0'
servers:
- url: https://{providerApiEndpoint}
  description: Anti-fraud provider endpoint URL.
  variables:
    providerApiEndpoint:
      description: Anti-fraud provider endpoint URL.
      default: '{providerApiEndpoint}'
tags:
- name: Anti-Fraud Flow
paths:
  /pre-analysis:
    post:
      tags:
      - Anti-Fraud Flow
      summary: VTex 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.


        >⚠️ 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 > Payments > Settings> Gateway affiliations tab > {your anti-fraud provider option}** 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 to update the connector.


        >⚠️ The pre-analysis does not exclude the need for full analysis after payments authorization.


        ## Permissions


        This endpoint does not require permissions.'
      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'
              examples:
                response:
                  value:
                    id: D3AA1FC8372E430E8236649DB5EBD08E
                    tid: 4692c1f54d514fe69da0b472a3b2a770
                    code: customCode
                    message: customMessage
                    status: approved
                    score: 5.01
                    analysisType: automatic
                    responses:
                      foo: anyFoo
                      custom: customAnyValue
      deprecated: false
  /transactions:
    post:
      tags:
      - Anti-Fraud Flow
      summary: VTex Send Anti-fraud Data
      description: 'Receives a new transaction anti-fraud data. This step is performed only if all payments are authorized.


        VTEX 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.


        ## Permissions


        This endpoint does not require permissions.'
      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: received
                score: 5.01
                analysisType: automatic
                responses:
                  foo: anyFoo
                  custom: customAnyValue
      deprecated: false
  /transactions/{transactionId}:
    put:
      tags:
      - Anti-Fraud Flow
      summary: VTex Update Anti-fraud Transactions (optional)
      description: 'Receives a new transaction anti-fraud data. This step is performed only if all payments are authorized.


        VTEX 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.


        ## Permissions


        This endpoint does not require permissions.'
      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
                analysisType: automatic
                responses: null
      deprecated: false
  /manifest:
    get:
      tags:
      - Anti-Fraud Flow
      summary: VTex List Anti-fraud Provider Manifest
      description: 'Returns the custom fields of the anti-fraud provider manifest.


        ## Permissions


        This endpoint does not require authentication or permissions.'
      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'
              examples:
                response:
                  value:
                    cardholderDocument: required
                    customFields:
                    - name: ApiKey
                      type: text
                    - name: AnalysisLocation
                      type: select
                      options:
                      - text: MEX
                        value: Latin America
                      - text: USA
                        value: United States
      deprecated: false
  /transactions/{transactions.id}:
    get:
      tags:
      - Anti-Fraud Flow
      summary: VTex 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.


        ## Permissions


        This endpoint does not require permissions.'
      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
      deprecated: false
  /transactions/{transactions.Id}:
    delete:
      tags:
      - Anti-Fraud Flow
      summary: VTex 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.


        This endpoint is not mandatory for the antifraud flow to work. Check this developer guide for more details.


        ## Permissions


        This endpoint does not require permissions.'
      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
      deprecated: false
components:
  schemas:
    Success:
      title: Success
      required:
      - customFields
      type: object
      properties:
        cardholderDocument:
          type: string
          description: 'Indicates the requirement of cardholder document in card transactions. The field has three possible values: `required`, `optional`, or `unused`.'
        customFields:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Custom fields information.
      example:
        customFields:
        - name: ApiKey
          type: text
        - name: AnalysisLocation
          type: select
          options:
          - text: MEX
            value: Latin America
          - text: USA
            value: United States
    SendAntifraudData:
      required:
      - id
      - tid
      - code
      - message
      - status
      - score
      - analysisType
      - responses
      type: object
      properties:
        id:
          type: string
          description: VTEX transaction ID. The ID of this transaction must be in the response.
          example: D3AA1F
        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.
          example: 4692c1
        code:
          type: string
          description: Error code returned from provider. It will be logged in transaction interactions log.
          example: customCode
        message:
          type: string
          description: Error message returned from provider. It will be logged in transaction interactions log.
          example: customMessage
        status:
          description: Pre-analysis status from provider. Must be `approved` or `denied`.
          example: approved
          enum:
          - approved
          - denied
        score:
          type: number
          description: Value of the risk score. The maximum value is `100.00`, which means total fraud.
          example: 5.01
        analysisType:
          type: string
          description: Pre-analysis type. Must be `automatic`.
          example: automatic
        responses:
          $ref: '#/components/schemas/Responses'
    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
    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'
    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
    Responses:
      required:
      - foo
      - custom
      type: object
      description: Responses information.
      properties:
        foo:
          type: string
          description: Any foo information.
          example: anyFoo
        custom:
          type: string
          description: Any custom value.
          example: customAnyValue
    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'
    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'
    GetAntifraudStatus:
      required:
      - id
      - tid
      - status
      - fraudRiskPercentage
      - analysisType
      - responses
      type: object
      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'
    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
    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'
    ApproveAntifraudAnalysisResponse:
      required:
      - id
      - status
      - fraudRiskPercentage
      - analysisType
      - responses
      type: object
      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
          - 'null'
          description: Value dictionary to add custom responses from analysis.
    GetPaymentMethodsSupported:
      required:
      - name
      type: object
      properties:
        name:
          type: string
          description: Payment method name.
    SendAntifraudDataRequest:
      required:
      - id
      - reference
      - value
      - ip
      - store
      - deviceFingerprint
      - miniCart
      - payments
      - sellerId
      - hook
      - transactionStartDate
      type: object
      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.
          example: '2020-10-30T18:08:23Z'
        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
            required:
            - name
            - value
            properties:
              name:
                type: string
                description: Custom field name.
                example: Country
              value:
                type: string
                description: Custom field name.
                example: BRL
    Payment:
      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'
    UpdateAntifraudTransactionsoptionalRequest:
      required:
      - id
      - reference
      - value
      - ip
      - store
      - deviceFingerprint
      - miniCart
      - payments
      - hook
      type: object
      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
  parameters:
    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
    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
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        example: application/json
    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}}'
  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.'