VTEX Provider API

openapi: 3.2.0
info:
  title: VTex GiftCard Hub Provider API
  description: '>ℹ️ Check the new [Payments onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/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.


    The Gift Card Hub API allows interactions with all Gift card providers registered to a store from a single point.


    Gift card providers are systems capable of providing cards to be used in the buying process.


    The following is the sequence diagram that represents calls in the purchase closing process.

    ![](https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/gift-card-integration-guide-provider-protocol-0.png)


    **Checkout + Gateway**: Systems responsible for the sale and for processing orders and payments.


    **Gift Card Hub**: System responsible for managing multiple registered Gift card providers for a store.


    **Gift Card Provider**: System responsible for providing the Gift cards available to the user not closing a purchase. This system can be implemented by third parties.


    ## GiftCard Hub API Index


    ### Provider


    - `PUT` [Create/Update GiftCard Provider by ID](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#put-/api/giftcardproviders/-giftCardProviderId-)

    - `GET` [Get GiftCard Provider by ID](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#get-/api/giftcardproviders/-giftCardProviderId-)

    - `GET` [List All GiftCard Providers](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#get-/api/giftcardproviders)

    - `DELETE` [Delete GiftCard Provider by ID](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#delete-/api/giftcardproviders/-giftCardProviderId-)


    ### Transaction


    - `POST` [Create GiftCard in GiftCard Provider](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#post-/api/giftcardproviders/-giftCardProviderId-/giftcards)

    - `POST` [Get GiftCard from GiftCard Provider](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#post-/api/giftcardproviders/-giftCardProviderId-/giftcards/_search)

    - `GET` [Get GiftCard from GiftCard Provider by ID](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#get-/api/giftcardproviders/-giftCardProviderId-/giftcards/-giftCardId-)

    - `POST` [Create GiftCard Transaction](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#post-/api/giftcardproviders/-giftCardProviderId-/giftcards/-giftCardId-/transactions)

    - `GET` [Get GiftCard Transaction by ID](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#get-/api/giftcardproviders/-giftCardProviderId-/giftcards/-giftCardId-/transactions/-transactionId-)

    - `GET` [List All GiftCard Transactions](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#get-/api/giftcardproviders/-giftCardProviderId-/giftcards/-giftCardId-/transactions)

    - `GET` [Get GiftCard Transaction Authorization](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#get-/api/giftcardproviders/-giftCardProviderId-/giftcards/-giftCardId-/transactions/-tId-/authorization)

    - `POST` [Cancel GiftCard Transaction](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#post-/api/giftcardproviders/-giftCardProviderId-/giftcards/-giftCardId-/transactions/-tId-/cancellations)

    - `GET` [List All GiftCard Transactions Cancellations](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#get-/api/giftcardproviders/-giftCardProviderId-/giftcards/-giftCardId-/transactions/-tId-/cancellations)

    - `POST` [Settle GiftCard Transaction](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#post-/api/giftcardproviders/-giftCardProviderId-/giftcards/-giftCardId-/transactions/-tId-/settlements)

    - `GET` [List All GiftCard Transactions Settlements](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#get-/api/giftcardproviders/-giftCardProviderId-/giftcards/-giftCardId-/transactions/-tId-/settlements)'
  contact: {}
  version: '1.0'
servers:
- url: https://{accountName}.{environment}.com.br
  description: VTEX server URL.
  variables:
    accountName:
      description: Name of the VTEX account. Used as part of the URL.
      default: apiexamples
    environment:
      description: Environment to use. Used as part of the URL.
      enum:
      - vtexcommercestable
      default: vtexcommercestable
security:
- appKey: []
  appToken: []
- VtexIdclientAutCookie: []
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.


        ## Permissions


        Any 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | GiftCard | GiftCard | **View Gift Card providers** |


        There 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).


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


        ## Permissions


        Any 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | GiftCard | GiftCard | **View Gift Card providers** |


        There 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).


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


        ## Permissions


        Any 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | GiftCard | GiftCard | **Edit Gift Card providers** |


        There 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).


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


        ## Permissions


        Any 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:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | GiftCard | GiftCard | **Edit Gift Card providers** |


        There 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).


        >❗ 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:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
      description: Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken
      description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    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.'