VTEX Provider API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Account Provider 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: Provider
paths:
  /api/giftcardproviders:
    get:
      tags:
      - Provider
      summary: VTex List All GiftCard Providers
      description: "Returns a collection of gift card providers from a store.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      operationId: ListAllGiftCardProviders
      parameters:
      - name: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - 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
          default: application/json
      - name: REST-Range
        in: header
        description: Pagination control. This query variable must follow the format `_resources={from}-{to}_`.
        required: false
        style: simple
        schema:
          type: string
          default: resources=0-49
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: Gift card provider identification.
                    serviceUrl:
                      type: string
                      description: URL from the provider.
                    oauthProvider:
                      type: string
                      description: Provider's authentication.
                    preAuthEnabled:
                      type: boolean
                      description: Related to the pre-authorization that can happen on the transaction generated through the provider.
                    cancelEnabled:
                      type: boolean
                      description: Indicates whether it is possible to cancel the transaction, generated through the provider.
                    _self:
                      type: object
                      description: Object that carries an auto reference from the provider at the Hub (on its API).
                      properties:
                        href:
                          type: string
                          description: This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`.
              example:
              - id: GiftCardExample
                serviceUrl: https://api.vtex.com.br/basedevmkp
                oauthProvider: vtex
                preAuthEnabled: true
                cancelEnabled: true
                _self:
                  href: cosmet/giftcardproviders/GiftCardExample
              - id: GiftCardExample2
                serviceUrl: https://giftcard--cosmetics2.myvtex.com/my-provider
                oauthProvider: vtex
                caption: My Updated Gift Card Provider
                preAuthEnabled: true
                cancelEnabled: true
                _self:
                  href: cosmet/giftcardproviders/GiftCardExample2
      deprecated: false
  /api/giftcardproviders/{giftCardProviderId}:
    get:
      tags:
      - Provider
      summary: VTex Get GiftCard Provider by ID
      description: "Returns a gift card provider from a store.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      operationId: GetGiftCardProviderbyID
      parameters:
      - name: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - 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
          default: application/json
      - name: giftCardProviderId
        in: path
        description: Gift card provider identification.
        required: true
        style: simple
        schema:
          type: string
          example: GiftCardExample
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Gift card provider identification.
                  serviceUrl:
                    type: string
                    description: URL from the provider.
                  oauthProvider:
                    type: string
                    description: Provider's authentication.
                  caption:
                    type: string
                    description: Description about the provider.
                  preAuthEnabled:
                    type: boolean
                    description: Related to the pre-authorization that can happen on the transaction generated through the provider.
                  cancelEnabled:
                    type: boolean
                    description: Indicates whether it is possible to cancel the transaction, generated through the provider.
                  _self:
                    type: object
                    description: Object that carries an auto reference from the provider at the Hub (on its API).
                    items:
                      type: object
                      properties:
                        href:
                          type: string
                          description: This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`.
              example:
                id: GiftCardExample
                serviceUrl: https://api.vtex.com.br/basedevmkp
                oauthProvider: vtex
                caption: My Updated Gift Card Provider
                preAuthEnabled: true
                cancelEnabled: true
                _self:
                  href: cosmet/giftcardproviders/GiftCardExample
        '500':
          description: Object reference not set to an instance of an object (The gift card provider described does not exist).
      deprecated: false
    put:
      tags:
      - Provider
      summary: VTex Create/Update GiftCard Provider by ID
      description: "Create or update a gift card provider from a store.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Edit Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      operationId: Create/UpdateGiftCardProviderbyID
      parameters:
      - name: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - 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
          default: application/json
      - name: giftCardProviderId
        in: path
        description: Gift card provider identification.
        required: true
        style: simple
        schema:
          type: string
          example: GiftCardExample
      requestBody:
        content:
          application/vnd.vtex.giftcardproviders.v1+json:
            schema:
              $ref: '#/components/schemas/CreateUpdateGiftCardProviderbyIDRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Gift card provider identification.
                  serviceUrl:
                    type: string
                    description: URL from the provider.
                  oauthProvider:
                    type: string
                    description: Provider's authentication.
                  preAuthEnabled:
                    type: boolean
                    description: Related to the pre-authorization that can happen on the transaction generated through the provider.
                  cancelEnabled:
                    type: boolean
                    description: Indicates whether it is possible to cancel the transaction, generated through the provider.
                  _self:
                    type: object
                    description: Object that carries an auto reference from the provider at the Hub (on its API).
                    items:
                      type: object
                      properties:
                        href:
                          type: string
                          description: This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`.
              example:
                id: GiftCardExample3
                serviceUrl: https://api.vtex.com.br/basedevmkp
                oauthProvider: vtex
                preAuthEnabled: true
                cancelEnabled: true
                _self:
                  href: cosmetics2/giftcardproviders/GiftCardExample3
      deprecated: false
    delete:
      tags:
      - Provider
      summary: VTex Delete GiftCard Provider by ID
      description: "Delete a gift card provider from a store.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Edit Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      operationId: DeleteGiftCardProviderbyID
      parameters:
      - name: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - 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
          default: application/json
      - name: giftCardProviderId
        in: path
        description: Gift card provider identification.
        required: true
        style: simple
        schema:
          type: string
          example: GiftCardExample
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '404':
          description: 'The gift card provider described does not exist.

            '
      deprecated: false
components:
  schemas:
    CreateUpdateGiftCardProviderbyIDRequest:
      required:
      - serviceUrl
      - oauthProvider
      - preAuthEnabled
      - cancelEnabled
      type: object
      properties:
        serviceUrl:
          type: string
          description: URL from the provider.
          example: https://api.vtex.com.br/example
        oauthProvider:
          type: string
          description: Provider's authentication.
          example: vtex
        preAuthEnabled:
          type: boolean
          description: Related to the pre-authorization that can happen on the transaction generated through the provider.
          example: true
        cancelEnabled:
          type: boolean
          description: Indicates whether it is possible to cancel the transaction, generated through the provider.
          example: true
        appKey:
          type: string
          description: Credential provided by the merchant that VTEX will use for identification.
          example: key
        appToken:
          type: string
          description: Credential provided by the merchant that VTEX will use for identification.
          example: token
  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.'