VTEX OAuth Flow API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account OAuth Flow 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: OAuth Flow
paths:
  /authorization/token:
    post:
      tags:
      - OAuth Flow
      summary: VTex 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
      deprecated: false
  /redirect:
    get:
      tags:
      - OAuth Flow
      summary: VTex 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.
      deprecated: false
  /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.
      deprecated: false
  /authorization/credentials:
    get:
      tags:
      - OAuth Flow
      summary: VTex 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:
  schemas:
    1.RetrieveTokenRequest:
      required:
      - applicationId
      - returnUrl
      type: object
      properties:
        applicationId:
          type: string
          description: This value is always identified as `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 the user.
      example:
        applicationId: vtex
        returnUrl: https://storevtex.vtexpayments.com/?authorizationCode=
    3.GetCredentials:
      required:
      - applicationId
      - appKey
      - appToken
      type: object
      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.
      example:
        applicationId: vtex
        appKey: c5a5e3f1-4a77-4a00-8b53-0d1adb3e9628
        appToken: 57ea254d-f3d3-488d-88d7-129766037ed1
    1.RetrieveToken:
      required:
      - applicationId
      - token
      type: object
      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.
      example:
        applicationId: vtex
        token: 358a5bea-07d0-4122-888a-54ab70b5f02f
  parameters:
    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}}'
    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}}'
  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.'