VTEX Transactions API

openapi: 3.2.0
info:
  title: VTex Giftcard Provider Protocol Transactions API
  description: ">ℹ️ Onboarding guide\n>\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.\n\nThe **Gift Card Provider Protocol** is a set of definitions to help you integrate your Gift Card API into VTEX platform. \n\nTo achieve this, you need to implement a web API (REST) following the specifications from this documentation and configure your provider in your store using [Gift Card Hub API](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#overview).\n\n## Giftcard Provider Protocol API Index\n\n### Gift Cards\n\n- `POST` [Create a gift card](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#post-/giftcards)\n- `GET` [Get a gift card by ID](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#get-/giftcards/-giftCardId-)\n- `POST` [List all gift cards](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#post-/giftcards/_search)\n\n### Transactions\n\n- `POST` [Create a gift card transaction](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#post-/giftcards/-giftCardId-/transactions)\n- `GET` [Get a gift card transaction by ID](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#get-/giftcards/-giftCardId-/transactions/-transactionId-)\n- `GET` [List all gift card transactions](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#get-/giftcards/-giftCardId-/transactions)\n- `GET` [Get a gift card transaction authorization](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#get-/giftcards/-giftCardId-/transactions/-transactionId-/authorization)\n- `POST` [Cancel a gift card transaction](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#post-/giftcards/-giftCardId-/transactions/-transactionId-/cancellations)\n- `GET` [List all gift card transactions cancellations](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#get-/giftcards/-giftCardId-/transactions/-transactionId-/cancellations)\n- `POST` [Settle a gift card transaction](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#post-/giftcards/-giftCardId-/transactions/-tId-/settlements)\n- `GET` [List all gift card transactions settlements](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#get-/giftcards/-giftCardId-/transactions/-tId-/settlements)"
  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:
    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'
    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
    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.
    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'
    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`.
    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
    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'
    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
    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
    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
    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
  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-).