openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Session API
  description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\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).\r\n\r\n## Anti-fraud Provider API Index\r\n\r\n### Anti-fraud  Flow\r\n\r\n- `POST` [Send Anti-fraud Pre-Analysis Data (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/pre-analysis)\r\n- `POST` [Send Anti-fraud Data](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/transactions)\r\n- `PUT` [Update Anti-fraud Transactions (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#put-/transactions/-transactionId-)\r\n- `GET` [List Anti-fraud Provider Manifest](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/manifest)\r\n- `GET` [Get Anti-fraud Status](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/transactions/-transactions.id-)\r\n- `DELETE` [Stop Anti-fraud Analysis (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#delete-/transactions/-transactions.Id-)\r\n\r\n### OAuth Flow\r\n\r\n1. `POST` [Retrieve Token](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/authorization/token)\r\n2. `GET` [Redirect](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/redirect)\r\n3. `GET` [Return to VTEX](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorizationCode)\r\n4. `GET` [Get Credentials](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorization/credentials)"
  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: Session
  description: ''
paths:
  /api/sessions:
    post:
      tags:
      - Session
      summary: VTex Create new session
      description: "Creates a new session and returns a session token and a segment token. Also stores `vtex_session` and `vtex_segment` cookies, with the same values returned in the response.\n\r\n\rAll parameters in the body that are not within the public namespace will be ignored. Query string items will automatically be added to the public namespace.\n\r\n\rNo authentication is required.\n\r\n\r>⚠️ The Session Manager API uses the `vtex_session` and `vtex_segment` cookies to store the data required to identify the user and the session. These cookies are stored in the user's browser when the session is created and sent automatically in every request to that domain. You will have to reproduce that by sending these cookies as headers in other requests to Session Manager API in order for it to work outside of a browser environment."
      operationId: Createnewsession
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEditSessionRequest'
            example:
              public:
                variable1:
                  value: value1
                variable2:
                  value: value2
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEditSessionResponse'
              example:
                sessionToken: eyJhbGciOiJFUzI1NiIsImtpZCI6IjM5MEI4MTM1RDUzQ0MwMUY0RjA4N0YwMzA2RjhDODMzNzBDMjY4M0UiLCJ0eXAiOiJqd3QifQ.eyJhY2NvdW50LmlkIjoiYThiMjdmYjQtNjUxNi00Y2MwLTgyYjYtYTVmMmIwMTFlNmUyIiwiaWQiOiIyNmQyY2I2Yy0yMTNlLTQ5MzYtOWUyYS0xZDFlMjk5ZWMzM2IiLCJ2ZXJzaW9uIjoyLCJzdWIiOiJzZXNzaW9uIiwiYWNjb3VudCI6InNlc3Npb24iLCJleHAiOjE2OTM1Nzg5NzYsImlhdCI6MTY5Mjg4Nzc3NiwiaXNzIjoidG9rZW4tZW1pdHRlciIsImp0aSI6IjhiYWU2NzdmLWE0NTAtNGI0OC05YTBkLTViMzAwYjNiY2NkOCJ9.Ak1bn2xEA1A5dVN4qR6RI8vnZpSpLXyVxFCthMoVjmWn0HlP5BqMHEMYApDj8TPPhyxT0hGT0vkmvMQa2Mprrw
                segmentToken: eyJjYW1wYWlnbnMiOm51bGwsImNoYW5uZWwiOiIxIiwicHJpY2VUYWJsZXMiOm51bGwsInJlZ2lvbklkIjpudWxsLCJ1dG1fY2FtcGFpZ24iOm51bGwsInV0bV9zb3VyY2UiOm51bGwsInV0bWlfY2FtcGFpZ24iOm51bGwsImN1cnJlbmN5Q29kZSI6IkJSTCIsImN1cnJlbmN5U3ltYm9sIjoiUiQiLCJjb3VudHJ5Q29kZSI6IkJSQSIsImN1bHR1cmVJbmZvIjoiZW4tVVMiLCJjaGFubmVsUHJpdmFjeSI6InB1YmxpYyJ9
      deprecated: false
    get:
      tags:
      - Session
      summary: VTex Get session
      description: "Retrieves information from a previously created sesssion.\n\r\n\r>⚠️ The Session Manager API uses the `vtex_session` and `vtex_segment` cookies to store the data required to identify the user and the session. These cookies are stored in the user's browser when the session is created and sent automatically in every request to that domain. You will have to reproduce that by sending these cookies as headers to Session Manager API in order for it to work outside of a browser environment."
      operationId: GetSession
      parameters:
      - name: items
        in: query
        description: "Items are the keys of the values you wish to get. They follow the format `namespace1.key1,namespace2.key2`.\n\r\n\rIf you wish to recover the data sent on [Create new session](https://developers.vtex.com/docs/api-reference/session-manager-api#post-/api/sessions), it should be `public.{key}`, replacing `{key}` with the name of the custom property you created. Following the example request presented in [Create new session](https://developers.vtex.com/docs/api-reference/session-manager-api#post-/api/sessions), it would be `public.variable1,public.variable2`.\n\r\n\rIf you want to retrieve all keys from Session Manager, you can use the wildcard operator (`*`) as a value for this query parameter."
        required: true
        style: form
        explode: true
        schema:
          type: string
          example: '*'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSessionResponse'
              example:
                id: 26d2cb6c-213e-4936-9e2a-1d1e299ec33b
                namespaces:
                  account:
                    id:
                      value: a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2
                      keepAlive: true
                    accountName:
                      value: apiexamples
                  store:
                    channel:
                      value: '1'
                    countryCode:
                      value: BRA
                    cultureInfo:
                      value: en-US
                    currencyCode:
                      value: BRL
                    currencySymbol:
                      value: R$
                    channelPrivacy:
                      value: public
                  public:
                    variable1:
                      value: value1
                    variable2:
                      value: value2
                  checkout:
                    regionId:
                      value: v2.1BB18CE648B5111D0933734ED83EC783
      security:
      - vtex_session: []
        vtex_segment: []
      deprecated: false
    patch:
      tags:
      - Session
      summary: VTex Edit session
      description: "Edits information from a previously created sesssion.\n\r\n\rThis endpoint works the same way as the [Create new session](https://developers.vtex.com/docs/api-reference/session-manager-api#post-/api/sessions) endpoint, but when the request is sent with a `vtex_session` and the `vtex_segment` cookies in the header, it retrieves the session first and then applies the changes instead of generating a new one.\n\r\n\rOnly keys inside the `public` namespace in the request body are considered, and query parameters are automatically added to the public namespace.\n\r\n\r>⚠️ The Session Manager API uses the `vtex_session` and `vtex_segment` cookies to store the data required to identify the user and the session. These cookies are stored in the user's browser when the session is created and sent automatically in every request to that domain. You will have to reproduce that by sending these cookies as headers to Session Manager API in order for it to work outside of a browser environment."
      operationId: Editsession
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEditSessionRequest'
            example:
              public:
                variable2:
                  value: value2_patched
                variable3:
                  value: value3
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEditSessionResponse'
              example:
                sessionToken: eyJhbGciOiJFUzI1NiIsImtpZCI6IjM5MEI4MTM1RDUzQ0MwMUY0RjA4N0YwMzA2RjhDODMzNzBDMjY4M0UiLCJ0eXAiOiJqd3QifQ.eyJhY2NvdW50LmlkIjoiYThiMjdmYjQtNjUxNi00Y2MwLTgyYjYtYTVmMmIwMTFlNmUyIiwiaWQiOiIyNmQyY2I2Yy0yMTNlLTQ5MzYtOWUyYS0xZDFlMjk5ZWMzM2IiLCJ2ZXJzaW9uIjoyLCJzdWIiOiJzZXNzaW9uIiwiYWNjb3VudCI6InNlc3Npb24iLCJleHAiOjE2OTM1Nzg5NzYsImlhdCI6MTY5Mjg4Nzc3NiwiaXNzIjoidG9rZW4tZW1pdHRlciIsImp0aSI6IjhiYWU2NzdmLWE0NTAtNGI0OC05YTBkLTViMzAwYjNiY2NkOCJ9.Ak1bn2xEA1A5dVN4qR6RI8vnZpSpLXyVxFCthMoVjmWn0HlP5BqMHEMYApDj8TPPhyxT0hGT0vkmvMQa2Mprrw
                segmentToken: eyJjYW1wYWlnbnMiOm51bGwsImNoYW5uZWwiOiIxIiwicHJpY2VUYWJsZXMiOm51bGwsInJlZ2lvbklkIjpudWxsLCJ1dG1fY2FtcGFpZ24iOm51bGwsInV0bV9zb3VyY2UiOm51bGwsInV0bWlfY2FtcGFpZ24iOm51bGwsImN1cnJlbmN5Q29kZSI6IkJSTCIsImN1cnJlbmN5U3ltYm9sIjoiUiQiLCJjb3VudHJ5Q29kZSI6IkJSQSIsImN1bHR1cmVJbmZvIjoiZW4tVVMiLCJjaGFubmVsUHJpdmFjeSI6InB1YmxpYyJ9
      security:
      - vtex_session: []
        vtex_segment: []
      deprecated: false
components:
  schemas:
    CreateEditSessionResponse:
      type: object
      description: Object containing session token and segment token.
      properties:
        sessionToken:
          type: string
          description: Token that identifies the user's individual session.
        segmentToken:
          type: string
          description: Token that identifies the user's segment, shared with other users with similar navigation parameters.
      example:
        sessionToken: eyJhbGciOiJFUzI1NiIsImtpZCI6IjM5MEI4MTM1RDUzQ0MwMUY0RjA4N0YwMzA2RjhDODMzNzBDMjY4M0UiLCJ0eXAiOiJqd3QifQ.eyJhY2NvdW50LmlkIjoiYThiMjdmYjQtNjUxNi00Y2MwLTgyYjYtYTVmMmIwMTFlNmUyIiwiaWQiOiIyNmQyY2I2Yy0yMTNlLTQ5MzYtOWUyYS0xZDFlMjk5ZWMzM2IiLCJ2ZXJzaW9uIjoyLCJzdWIiOiJzZXNzaW9uIiwiYWNjb3VudCI6InNlc3Npb24iLCJleHAiOjE2OTM1Nzg5NzYsImlhdCI6MTY5Mjg4Nzc3NiwiaXNzIjoidG9rZW4tZW1pdHRlciIsImp0aSI6IjhiYWU2NzdmLWE0NTAtNGI0OC05YTBkLTViMzAwYjNiY2NkOCJ9.Ak1bn2xEA1A5dVN4qR6RI8vnZpSpLXyVxFCthMoVjmWn0HlP5BqMHEMYApDj8TPPhyxT0hGT0vkmvMQa2Mprrw
        segmentToken: eyJjYW1wYWlnbnMiOm51bGwsImNoYW5uZWwiOiIxIiwicHJpY2VUYWJsZXMiOm51bGwsInJlZ2lvbklkIjpudWxsLCJ1dG1fY2FtcGFpZ24iOm51bGwsInV0bV9zb3VyY2UiOm51bGwsInV0bWlfY2FtcGFpZ24iOm51bGwsImN1cnJlbmN5Q29kZSI6IkJSTCIsImN1cnJlbmN5U3ltYm9sIjoiUiQiLCJjb3VudHJ5Q29kZSI6IkJSQSIsImN1bHR1cmVJbmZvIjoiZW4tVVMiLCJjaGFubmVsUHJpdmFjeSI6InB1YmxpYyJ9
    CreateEditSessionRequest:
      title: CreateEditSessionRequest
      required:
      - public
      type: object
      properties:
        public:
          title: Public
          type: object
          properties:
            additionalProperties:
              type: object
              description: Custom property.
              properties:
                value:
                  type: string
                  description: Value of the custom property.
          example:
            variable2:
              value: value2
            variable3:
              value: value3
      example:
        public:
          variable2:
            value: value2
          variable3:
            value: value3
    GetSessionResponse:
      type: object
      properties:
        id:
          type: string
          description: Session ID.
        namespaces:
          type: object
          description: Object with namespaces, each containing a set of information about the session.
          properties:
            account:
              type: object
              description: Account information related to the session.
              properties:
                id:
                  type: object
                  description: VTEX account ID.
                  properties:
                    value:
                      type: string
                      description: Value of the VTEX account ID.
                    keepAlive:
                      type: boolean
                      description: Determines whether or not the connection should be kept alive.
                accountName:
                  type: object
                  description: VTEX account name.
                  properties:
                    value:
                      type: string
                      description: Value of the VTEX account name.
            store:
              type: object
              description: Store information related to the session.
              properties:
                channel:
                  type: object
                  description: '[Trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV) ID.'
                  properties:
                    value:
                      type: string
                      description: Value of the [Trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV) ID.
                countryCode:
                  type: object
                  description: Country code.
                  properties:
                    value:
                      type: string
                      description: Value of the country code.
                cultureInfo:
                  type: object
                  description: Locale that provides culture-specific information, such as the language, sublanguage, country/region, calendar, and conventions associated with a particular culture. Read [this documentation](https://learn.microsoft.com/en-us/dotnet/api/system.globalization.cultureinfo?view=net-7.0#culture-names-and-identifiers) for more details.
                  properties:
                    value:
                      type: string
                      description: Value of the `cultureInfo` property.
                currencyCode:
                  type: object
                  description: Currency code.
                  properties:
                    value:
                      type: string
                      description: Value of the currency code.
                currencySymbol:
                  type: object
                  description: Currency symbol.
                  properties:
                    value:
                      type: string
                      description: Value of the currency symbol.
                channelPrivacy:
                  type: object
                  description: Defines whether or not the channel is private.
                  properties:
                    value:
                      type: string
                      description: Value containing the channel's privacy option.
            public:
              type: object
              description: Public and editable information related to the session.
              additionalProperties:
                type: object
                description: Custom property.
                properties:
                  value:
                    type: string
                    description: Value of the custom property.
            checkout:
              type: object
              description: Checkout information related to the session.
              properties:
                regionId:
                  type: object
                  description: ID of the session's region.
                  properties:
                    value:
                      type: string
                      description: Value of the Region ID.
      example:
        id: 26d2cb6c-213e-4936-9e2a-1d1e299ec33b
        namespaces:
          account:
            id:
              value: a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2
              keepAlive: true
            accountName:
              value: apiexamples
          store:
            channel:
              value: '1'
            countryCode:
              value: BRA
            cultureInfo:
              value: en-US
            currencyCode:
              value: BRL
            currencySymbol:
              value: R$
            channelPrivacy:
              value: public
          public:
            variable1:
              value: value1
            variable2:
              value: value2
          checkout:
            regionId:
              value: v2.1BB18CE648B5111D0933734ED83EC783
  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.'