VTEX OAuth Flow API

openapi: 3.2.0
info:
  title: VTex Anti-fraud Provider OAuth 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: 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.


        ## Permissions


        This endpoint does not require permissions.'
      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.


        At 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`.


        ## Permissions


        This endpoint does not require permissions.'
      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.


        The `returnUrl` must be filled with your query string **authorizationCode**.


        Example:


        If you receive the following URL:


        `https://store.vtex.com/return?authorizationCode=&otherparams...`


        and your **authorizationCode** is `pro2018`. Then, you redirect the store administrator to: `https://store.vtex.com/return?authorizationCode=pro2018&otherparams...`.


        ## Permissions


        This endpoint does not require permissions.'
      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.


        ## Permissions


        This endpoint does not require permissions.'
      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.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
    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
  parameters:
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        example: application/json
    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}}'
    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
    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.'