VTEX Transactions API

openapi: 3.2.0
info:
  title: VTex Giftcard Provider Protocol Transactions API
  description: '>ℹ️ Onboarding guide

    >

    > Check the new Payments onboarding guide.'
  contact: {}
  version: '1.0'
servers:
- url: https://{providerApiEndpoint}
  description: Gift card provider endpoint URL.
  variables:
    providerApiEndpoint:
      description: Gift card provider endpoint URL.
      default: '{providerApiEndpoint}'
security:
- appKey: []
  appToken: []
tags:
- name: Transactions
paths:
  /giftcards/{giftCardId}/transactions:
    post:
      tags:
      - Transactions
      summary: VTex Create a gift card transaction
      description: 'Creates a transaction (credit or debit) for a gift card in a gift card provider and authorizes the item reservation.


        > ℹ️ This request is made from VTEX to the gift card payment provider.


        ## Permissions


        Check with your service provider to know what permissions are needed.'
      operationId: CreateGiftCardTransaction
      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: giftCardId
        in: path
        description: Gift card identification.
        required: true
        style: simple
        schema:
          type: string
          example: '2'
      requestBody:
        content:
          application/vnd.vtex.giftcardproviders.v1+json:
            schema:
              $ref: '#/components/schemas/CreateGiftCardTransactionRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GiftCardTransactionResponse'
              example:
                cardId: '24'
                id: 68347b311ce5407c90fa5316975d047a
                _self:
                  href: gatewayqa/giftcards/24/transactions/68347b311ce5407c90fa5316975d047a
      deprecated: false
    get:
      tags:
      - Transactions
      summary: VTex List all gift card transactions
      description: 'Returns the IDs of all transactions performed in a gift card provider for a specific gift card.


        > ℹ️ This request is made from VTEX to the gift card payment provider.


        ## Permissions


        Check with your service provider to know what permissions are needed.'
      operationId: ListAllGiftCardTransactions
      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: giftCardId
        in: path
        description: Gift card identification.
        required: true
        style: simple
        schema:
          type: string
          example: '2'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GiftCardTransactionResponse'
              example:
              - cardId: 3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24
                id: 68347b311ce5407c90fa5316975d047a
                _self:
                  href: gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions/68347b311ce5407c90fa5316975d047a
              - cardId: 3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24
                id: e122ebd4501a4b3b93640b7444ac425d
                _self:
                  href: gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions/e122ebd4501a4b3b93640b7444ac425d
      deprecated: false
  /giftcards/{giftCardId}/transactions/{transactionId}:
    get:
      tags:
      - Transactions
      summary: VTex Get a gift card transaction by ID
      description: 'Returns a specific transaction for a gift card from a gift card provider.


        > ℹ️ This request is made from VTEX to the gift card payment provider.


        ## Permissions


        Check with your service provider to know what permissions are needed.'
      operationId: GetGiftCardTransactionbyID
      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: giftCardId
        in: path
        description: Gift card identification.
        required: true
        style: simple
        schema:
          type: string
          example: '6'
      - name: transactionId
        in: path
        description: Transaction identification.
        required: true
        style: simple
        schema:
          type: string
          example: b47690
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: number
                    description: Transaction value.
                  description:
                    type: string
                    description: Transaction description.
                  date:
                    type: string
                    description: Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`).
                  requestId:
                    type: string
                    description: VTEX request identifier.
                  settlement:
                    type: object
                    description: Settlement transaction information.
                    properties:
                      href:
                        type: string
                        description: Gift card resource URL. The first number described in the URL refers to the gift card identification. The second number, refers to the transaction identification.
                  cancellation:
                    type: object
                    description: Cancellation transaction information.
                    properties:
                      href:
                        type: string
                        description: Gift card resource URL. The first number described in the URL refers to the gift card identification. The second number, refers to the transaction identification.
                  authorization:
                    type: object
                    description: Authorization transaction information.
                    properties:
                      href:
                        type: string
                        description: Gift card resource URL. The first number described in the URL refers to the gift card identification. The second number, refers to the transaction identification.
                  operation:
                    type: string
                    description: Operation information (`Credit` or `Debit`).
              example:
                value: 140
                description: GiftCardProvider1
                date: '2023-06-02T18:24:49.252855Z'
                settlement:
                  href: /gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions/e122ebd4501a4b3b93640b7444ac425d/settlements
                cancellation:
                  href: /gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions/e122ebd4501a4b3b93640b7444ac425d/cancellations
                authorization:
                  href: /gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions/e122ebd4501a4b3b93640b7444ac425d/authorization
                operation: Debit
      deprecated: false
  /giftcards/{giftCardId}/transactions/{transactionId}/authorization:
    get:
      tags:
      - Transactions
      summary: VTex Get a gift card transaction authorization
      description: 'Returns information about a gift card transaction authorization from a gift card provider.


        > ℹ️ This request is made from VTEX to the gift card payment provider.


        ## Permissions


        Check with your service provider to know what permissions are needed.'
      operationId: GetGiftCardTransactionAuthorization
      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: giftCardId
        in: path
        description: Gift card identification.
        required: true
        style: simple
        schema:
          type: string
          example: '6'
      - name: transactionId
        in: path
        description: Transaction identification.
        required: true
        style: simple
        schema:
          type: string
          example: b47690
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
              example:
                oid: e122ebd4501a4b3b93640b7444ac425d
                value: 5.92
                date: '2019-03-18T14:42:32.1291783Z'
      deprecated: false
  /giftcards/{giftCardId}/transactions/{transactionId}/cancellations:
    post:
      tags:
      - Transactions
      summary: VTex Cancel a gift card transaction
      description: 'This request can be used to:


        1. Cancel a transaction for a specific gift card in a gift card provider.


        2. Cancel an item''s reservation or create a refund.


        > ℹ️ This request is made from VTEX to the gift card payment provider.


        ## Permissions


        Check with your service provider to know what permissions are needed.'
      operationId: CreateGiftCardTransactionCancellation
      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: giftCardId
        in: path
        description: Gift card identification.
        required: true
        style: simple
        schema:
          type: string
          example: '6'
      - name: transactionId
        in: path
        description: Transaction identification.
        required: true
        style: simple
        schema:
          type: string
          example: b476900c
      requestBody:
        content:
          application/vnd.vtex.giftcardproviders.v1+json:
            schema:
              $ref: '#/components/schemas/CreateGiftCardTransactionCancellationRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
              example:
                oid: 7582d93baccc44e9867b0b861696fc0a
                value: 4.1
                date: '2019-03-19T14:35:16.7157238Z'
      deprecated: false
    get:
      tags:
      - Transactions
      summary: VTex List all gift card transactions cancellations
      description: 'Returns all transactions cancelled for a specific gift card from a gift card provider.


        > ℹ️ This request is made from VTEX to the gift card payment provider.


        ## Permissions


        Check with your service provider to know what permissions are needed.'
      operationId: ListAllGiftCardTransactionsCancellations
      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: giftCardId
        in: path
        description: Gift card identification.
        required: true
        style: simple
        schema:
          type: string
          example: '6'
      - name: transactionId
        in: path
        description: Transaction identification.
        required: true
        style: simple
        schema:
          type: string
          example: b47690
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransactionResponse'
              example:
              - oid: 7582d93baccc44e9867b0b861696fc0a
                value: 4.1
                date: '2019-03-19T14:35:16.7157238Z'
      deprecated: false
  /giftcards/{giftCardId}/transactions/{tId}/settlements:
    post:
      tags:
      - Transactions
      summary: VTex Settle a gift card transaction
      description: 'Creates a transaction settlement for a specific gift card from a gift card provider.


        > ℹ️ This request is made from VTEX to the gift card payment provider.


        ## Permissions


        Check with your service provider to know what permissions are needed.'
      operationId: CreateGiftCardTransactionSettlement
      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: giftCardId
        in: path
        description: Gift card identification.
        required: true
        style: simple
        schema:
          type: string
          example: '2'
      - name: tId
        in: path
        description: Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.
        required: true
        style: simple
        schema:
          type: string
          example: 3146f46162f042f483cd3979ba4e8317
      requestBody:
        content:
          application/vnd.vtex.giftcardproviders.v1+json:
            schema:
              $ref: '#/components/schemas/CreateGiftCardTransactionSettlementRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
              example:
                oid: e122ebd4501a4b3b93640b7444ac425d
                value: 1.8
                date: '2019-03-18T14:42:32.1291783Z'
      deprecated: false
    get:
      tags:
      - Transactions
      summary: VTex List all gift card transactions settlements
      description: 'Returns all transactions settlements for a specific gift card from a gift card provider.


        > ℹ️ This request is made from VTEX to the gift card payment provider.


        ## Permissions


        Check with your service provider to know what permissions are needed.'
      operationId: ListAllGiftCardTransactionsSettlements
      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: giftCardId
        in: path
        description: Gift card identification.
        required: true
        style: simple
        schema:
          type: string
          example: '7'
      - name: tId
        in: path
        description: Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.
        required: true
        style: simple
        schema:
          type: string
          example: 3146f46162f042f483cd3979ba4e8317
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                required:
                - oid
                - value
                - date
                type: array
                description: Array containing gift card transactions settlements information.
                items:
                  type: object
                  description: Payment rules information.
                  properties:
                    oid:
                      type: string
                      description: Operation identification.
                    value:
                      type: number
                      description: Value information.
                    date:
                      type: string
                      description: Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`).
              example:
              - oid: faa6831230634c4b8fb897e02ba9c5a1
                value: 15
                date: '2023-06-02T18:24:49.252855Z'
              - oid: hbar6832580652c4b8fb653f15ba9c5a7
                value: 40
                date: '2023-06-04T15:00:35.252855Z'
      deprecated: false
components:
  schemas:
    ClientProfile:
      description: Client profile information.
      required:
      - email
      - firstName
      - lastName
      - document
      - phone
      - birthDate
      - isCorporate
      type: object
      properties:
        email:
          type: string
          description: Customer's email address.
          example: michael.scott96@mail.com
        firstName:
          type: string
          description: Customer's first name.
          example: Michael
        lastName:
          type: string
          description: Customer's last name.
          example: Scott
        document:
          type: string
          description: Document number informed by the customer.
          example: 02906792063
        phone:
          type: string
          description: Customer's phone number.
          example: '+551111111111'
        birthDate:
          type: string
          description: Customer's birth date.
          example: '0001-01-01T00:00:00'
        isCorporate:
          type: boolean
          description: Defines if the customer is a company (`true`) or not (`false`).
          example: false
    PriceTag:
      description: Price tag information.
      required:
      - name
      - value
      type: object
      properties:
        name:
          type: string
          description: Price tag name.
          example: discount@price-discount_store_183#4911bf6f-22a2-4af1-a365-cce895c3df2c
        value:
          type: integer
          description: Price tag value.
          example: 0
    TransactionResponse:
      description: Transaction response information.
      required:
      - oid
      - value
      - date
      type: object
      properties:
        oid:
          type: string
          description: Operation identification.
        value:
          type: number
          description: Value information.
        date:
          type: string
          description: Date information.
    CreateGiftCardTransactionSettlementRequest:
      description: Settle a gift card transaction request information.
      required:
      - value
      - requestId
      type: object
      properties:
        value:
          type: number
          description: Transaction value.
          example: 1.8
        requestId:
          type: string
          description: Request identification of the transaction.
          example: 12093812masoidj120398
    Shipping:
      description: Shipping information.
      required:
      - receiverName
      - postalCode
      - city
      - state
      - country
      - street
      - number
      - neighborhood
      - complement
      - reference
      type: object
      properties:
        receiverName:
          type: string
          description: Name of the person who is going to receive the order.
          example: Michael Scott
        postalCode:
          type: string
          description: Postal code.
          example: '22250040'
        city:
          type: string
          description: City of the shipping address.
          example: Rio de Janeiro
        state:
          type: string
          description: State of the shipping address.
          example: RJ
        country:
          type: string
          description: Country of the shipping address.
          example: BRA
        street:
          type: string
          description: Street of the shipping address.
          example: Praia de Botafogo
        number:
          type: string
          description: Number of the building, house or apartment in the shipping address.
          example: '111'
        neighborhood:
          type: string
          description: Neighborhood of the address.
          example: Botafogo
        complement:
          type:
          - string
          - 'null'
          description: Complement to the shipping address in case it applies.
          example: House
        reference:
          type:
          - string
          - 'null'
          description: Complement that might help locate the shipping address more precisely in case of delivery.
          example: Subway
    CreateGiftCardTransactionCancellationRequest:
      description: Cancel a gift card transaction request information.
      required:
      - value
      - requestId
      type: object
      properties:
        value:
          type: number
          description: Transaction value.
          example: 4.1
        requestId:
          type: string
          description: Request identification of the transaction.
          example: 12093812masoidj120398
    OrderInfo:
      description: Order Information.
      type: object
      properties:
        orderId:
          type: string
          description: Order ID.
          example: v500
        sequence:
          type: integer
          description: Sequence number.
          example: 5006128
        cart:
          $ref: '#/components/schemas/Cart1'
        clientProfile:
          $ref: '#/components/schemas/ClientProfile'
        shipping:
          $ref: '#/components/schemas/Shipping'
    CreateGiftCardTransactionRequest:
      description: Create a gift card transaction request body information.
      required:
      - operation
      - value
      - description
      - redemptionToken
      - redemptionCode
      - requestId
      - orderInfo
      type: object
      properties:
        operation:
          type: string
          description: 'Type of operation. Possible values are: `Debit` or `Credit`.'
          example: Debit
        value:
          type: number
          description: Operation value.
          example: 3
        description:
          type: string
          description: Description information.
          example: GiftCardHub
        redemptionToken:
          type: string
          description: Gift card redemption token.
          example: b2dac6f2-f365-48cd-82a9-0b376a55557a
        redemptionCode:
          type: string
          description: Gift card identification code used at checkout. Minimum of 6 characters.
          example: '***********ASDQ'
        requestId:
          type: string
          description: Request identification of the transaction. You need to send a different `requestId` value every time you make a new transaction. If you send the same `requestId`two or more times with a specific `redemptionCode`or `redemptionToken`, the gift card balance will not be updated.
          example: B56CBE231DEE4E1A859183C1030CE926
        orderInfo:
          $ref: '#/components/schemas/OrderInfo'
    GiftCardTransactionResponse:
      description: Gift card transaction response information.
      required:
      - cardId
      - id
      - _self
      type: object
      properties:
        cardId:
          type: string
          description: Gift card identification.
        id:
          type: string
          description: Transaction identification.
        _self:
          $ref: '#/components/schemas/Self'
    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`.
    Cart1:
      description: Cart information.
      required:
      - items
      - grandTotal
      - discounts
      - shipping
      - taxes
      - itemsTotal
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item2'
          description: Items information.
        grandTotal:
          type: integer
          description: Total payment value.
          example: 0
        discounts:
          type: number
          description: Discounts value.
          example: -7.5
        shipping:
          type: number
          description: Shipping value.
          example: 7.27
        taxes:
          type: integer
          description: Taxes value.
          example: 0
        itemsTotal:
          type: number
          description: Total items value.
          example: 14.99
    Item2:
      description: Items information.
      required:
      - id
      - productId
      - refId
      - name
      - value
      - price
      - quantity
      - shippingDiscount
      - discount
      - priceTags
      type: object
      properties:
        id:
          type: string
          description: SKU ID.
          example: '2001023'
        productId:
          type: string
          description: Product ID.
          example: '2000492'
        refId:
          type: string
          description: Product Reference ID.
          example: '35994'
        name:
          type: string
          description: Product name.
          example: Vaporizador Des. ColC4nia Branco
        value:
          type: number
          description: Product value.
          example: 14.99
        price:
          type: number
          description: Product price.
          example: 14.99
        quantity:
          type: integer
          description: Product quantity.
          example: 1
        shippingDiscount:
          type: integer
          description: Discount to be applied for the shipping value.
          example: 0
        discount:
          type: number
          description: Discount applied on item.
          example: -7.5
        priceTags:
          type: array
          description: Array of price tags, each of which modifies the price in some way, like discounts or rates that apply to the item in the context of the order.
          items:
            $ref: '#/components/schemas/PriceTag'
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-PROVIDER-API-AppKey
      description: Unique identifier created by the provider and configured through [Giftcard Hub API](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#put-/api/giftcardproviders/-giftCardProviderId-).
    appToken:
      type: apiKey
      in: header
      name: X-PROVIDER-API-AppToken
      description: Unique token created by the provider and configured through [Giftcard Hub API](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#put-/api/giftcardproviders/-giftCardProviderId-).