VTEX Gift Cards API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Gift Cards 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: Gift Cards
paths:
  /giftcards/_search:
    post:
      tags:
      - Gift Cards
      summary: VTex List all gift cards
      description: "Returns a list of all gift cards available from a gift card provider for a specific customer's cart.\r\n\r\n> ℹ️ This request is made from VTEX to the gift card payment provider.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed."
      operationId: ListAllGiftCards
      parameters:
      - name: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/vnd.vtex.giftcardproviders.v1+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/vnd.vtex.giftcardproviders.v1+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
      requestBody:
        content:
          application/vnd.vtex.giftcardproviders.v1+json:
            schema:
              $ref: '#/components/schemas/ListAllGiftCardsRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/response'
              example:
              - id: 3ad63br54-988e-4a14-8b7f-31fc6a5b955c_24
                provider: ProviderName
                balance: 5.9
                _self:
                  href: /gatewayqa/giftcards/3ad63br54-988e-4a14-8b7f-31fc6a5b955c_24
      deprecated: false
  /giftcards/{giftCardId}:
    get:
      tags:
      - Gift Cards
      summary: VTex Get a gift card by ID
      description: "Returns information for a specific gift card from a gift card provider.\r\n\r\n> ℹ️ This request is made from VTEX to the gift card payment provider.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed."
      operationId: GetGiftCardbyID
      parameters:
      - name: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/vnd.vtex.giftcardproviders.v1+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/vnd.vtex.giftcardproviders.v1+json
      - name: giftCardId
        in: path
        description: Gift card identification.
        required: true
        style: simple
        schema:
          type: string
          example: '5'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Gift card identification.
                  redemptionToken:
                    type: string
                    description: Gift card redemption token.
                  redemptionCode:
                    type: string
                    description: Gift card identification code used at checkout. Minimum of 6 characters.
                  balance:
                    type: number
                    description: Gift card current balance. For newly created gift cards, the balance will be 0.0.
                  emissionDate:
                    type: string
                    description: Gift card creation date.
                  expiringDate:
                    type: string
                    description: Gift card expiration date.
                  currencyCode:
                    type: string
                    description: Currency code in ISO 4217.
                  discount:
                    type: boolean
                    description: Discount information.
                    deprecated: true
                  transactions:
                    type: object
                    description: Transactions information.
                    properties:
                      href:
                        type: string
                        description: Gift card resource URL. The number described in the URL refers to the gift card identification.
              example:
                id: '5'
                redemptionToken: 32ScL57220Vapb8pc50HJ3mWH1cl1L8x
                redemptionCode: '***********ASDQ'
                balance: 870
                emissionDate: '2014-04-24T20:22:58.163'
                expiringDate: '2016-01-01T00:00:00'
                currencyCode: USD
                discount: false
                transactions:
                  href: cards/954/transactions
      deprecated: false
  /giftcards:
    post:
      tags:
      - Gift Cards
      summary: VTex Create a gift card
      description: "Creates a gift card for a specific user in a gift card provider.\r\n\r\n> ℹ️ This request is made from VTEX to the gift card payment provider.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed."
      operationId: CreateGiftCard
      parameters:
      - name: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/vnd.vtex.giftcardproviders.v1+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/vnd.vtex.giftcardproviders.v1+json
      requestBody:
        content:
          application/vnd.vtex.giftcardproviders.v1+json:
            schema:
              $ref: '#/components/schemas/CreateGiftCardRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Gift card identification.
                  relationName:
                    type: string
                    description: Field to be filled in when it is not necessary to use a loyalty program for the gift card. Note that a new `relationNamevalue` is required for each new gift card to be created.
                  emissionDate:
                    type: string
                    description: Gift card creation date.
                  expiringDate:
                    type: string
                    description: Gift card expiration date.
                  caption:
                    type: string
                    description: Field to be filled in if a loyalty program must be created for the Gift Card.
                  restrictedToOwner:
                    type: boolean
                    description: The gift card can only be used for a specified client's ID.
                  multipleRedemptions:
                    type: boolean
                    description: The gift card can be used to make new purchases until its value is completely used.
                  multipleCredits:
                    type: boolean
                    description: The gift card balance can be changed.
                  profileId:
                    type: string
                    description: Client ID. You can use the customer's registered email or the `userId` parameter which can be found in the [Master Data](https://help.vtex.com/en/tutorial/master-data--4otjBnR27u4WUIciQsmkAw).
                  currencyCode:
                    type: string
                    description: Currency code in ISO 4217.
              example:
                id: '38'
                relationName: loyalty-program
                emissionDate: '2011-02-04T17:02:19.17'
                expiringDate: '2020-02-04T17:02:19.17'
                caption: Loyalty Program
                restrictedToOwner: true
                multipleRedemptions: true
                multipleCredits: true
                profileId: 92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff
                currencyCode: USD
      deprecated: false
components:
  schemas:
    Client:
      description: Customer information.
      required:
      - id
      - email
      - document
      type: object
      properties:
        id:
          type: string
          description: Customer's identification.
          example: 3b1abc17
        email:
          type: string
          description: Customer's email address.
          example: email@domain.com
        document:
          type: string
          description: Document number informed by the customer.
          example: '234235'
    CreateGiftCardRequest:
      description: Create a gift card request body information.
      required:
      - relationName
      - caption
      - profileId
      type: object
      properties:
        relationName:
          type: string
          description: Field to be filled in when it is not necessary to use a loyalty program for the gift card. Note that a new `relationNamevalue` is required for each new gift card to be created.
          example: loyalty-program
        emissionDate:
          type: string
          description: Gift card creation date.
          example: '2020-08-01T13:15:30Z'
        expiringDate:
          type: string
          description: Gift card expiration date.
          example: '2020-09-01T13:15:30Z'
        caption:
          type: string
          description: Field to be filled in if a loyalty program must be created for the gift card.
          example: Loyalty program
        restrictedToOwner:
          type: boolean
          description: The gift card can only be used for a specified client's ID.
          example: true
        multipleRedemptions:
          type: boolean
          description: The gift card can be used to make new purchases until its value is completely used.
          example: true
        multipleCredits:
          type: boolean
          description: The gift card balance can be changed.
          example: true
        profileId:
          type: string
          description: Client ID. You can use the customer's registered email or the `userId` parameter which can be found in the [Master Data](https://help.vtex.com/en/tutorial/master-data--4otjBnR27u4WUIciQsmkAw).
          example: 92de2249-0e02-4ca9-a4aa-a09cc9d8f7ff
        currencyCode:
          type: string
          description: Currency code in ISO 4217.
          example: USD
    ListAllGiftCardsRequest:
      description: Gift cards information.
      required:
      - client
      - cart
      type: object
      properties:
        client:
          $ref: '#/components/schemas/Client'
        cart:
          $ref: '#/components/schemas/Cart'
    Item:
      description: Items information.
      required:
      - productId
      - id
      - refId
      - name
      - price
      - quantity
      type: object
      properties:
        productId:
          type: string
          description: Product ID.
          example: '2000000'
        id:
          type: string
          description: The ID of the SKU in VTEX platform.
          example: '2000002'
        refId:
          type: string
          description: Product Reference ID.
          example: MEV41
        name:
          type: string
          description: Product name.
          example: Shoes
        price:
          type: integer
          description: Product price.
          example: 200
        quantity:
          type: integer
          description: Product quantity.
          example: 1
    Self:
      required:
      - href
      type: object
      description: It is an 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`.
    Cart:
      description: Cart information.
      required:
      - grandTotal
      - relationName
      - redemptionCode
      - discounts
      - shipping
      - taxes
      - items
      - itemsTotal
      type: object
      properties:
        grandTotal:
          type: integer
          description: Total payment value.
          example: 182
        relationName:
          type: string
          nullable: true
          description: Represents the relationship between the client and the store.
          example: null
        redemptionCode:
          type: string
          description: Gift card identification code used at checkout. Minimum of 6 characters.
          example: BAHD-ASDB-ADQW-ASDQ
        discounts:
          type: integer
          description: Discounts value.
          example: 20
        shipping:
          type: integer
          description: Shipping value.
          example: 2
        taxes:
          type: integer
          description: Taxes value.
          example: 0
        items:
          type: array
          description: Items information.
          items:
            $ref: '#/components/schemas/Item'
        itemsTotal:
          type: integer
          description: Total items value.
          example: 200
    response:
      description: Response information.
      required:
      - id
      - provider
      - balance
      - _self
      type: object
      properties:
        id:
          type: string
          description: Gift card identification.
        provider:
          type: string
          description: Provider's name.
        balance:
          type: number
          description: Gift card current balance.
        _self:
          $ref: '#/components/schemas/Self'
  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.'