VTEX Transaction Flow API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Transaction Flow 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: Transaction Flow
paths:
  /api/pvt/transactions/{transactionId}/settlement-request:
    post:
      tags:
      - Transaction Flow
      summary: VTex Settle the transaction
      description: "Settles the transaction amount. A payment settled means that the seller will receive the value of the purchase value after bank conciliation.\r\n\r\n>ℹ️ This call is mandatory to complete a transaction and its payments.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| PCI Gateway | Payment-Make Payments | **Process payments** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      operationId: Settlethetransaction
      parameters:
      - $ref: '#/components/parameters/transactionId'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettlethetransactionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettleResponse'
              example:
                id: null
                token: 2BCA48B4FBCB42D0B8A19EE965712AD8
                status: 11
                statusDetail: Settling
                processingDate: '2023-12-14T22:45:50.9977213Z'
                refundedValue: 0
                refundedToken: null
                message: null
                code: null
                connectorRefundedValue: 0
                cancelledValue: 0
      deprecated: false
  /api/pvt/transactions/{transactionId}/refunding-request:
    post:
      tags:
      - Transaction Flow
      summary: VTex Refund the transaction
      description: "Refunds the amount of the transaction that was previously settled.\r\n\r\nAfter a transaction is settled, this request can be used to partially or fully refund the transaction amount.\r\n\r\nDue to acquirer rules, it is not possible to perform this step online against the acquirer, and, if an error occurrs, we notify the seller company responsible by email to manually check the transaction status against the acquirer.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| PCI Gateway | Payment-Make Payments | **Process payments** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      operationId: Refundthetransaction
      parameters:
      - $ref: '#/components/parameters/transactionId'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundthetransactionRequest'
            example:
              value: 2300
              freight: 200
              tax: 0
              minicart:
                items:
                - id: '122323'
                  name: Tenis Preto I
                  value: 1000
                  quantity: 1
                  shippingDiscount: 0
                  discount: 50
                - id: '122324'
                  name: Tenis Nike Azul
                  value: 1100
                  quantity: 1
                  shippingDiscount: 0
                  discount: 50
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettleResponse'
              example:
                id: null
                token: 2BCA48B4FBCB42D0B8A19EE965712AD8
                status: 11
                statusDetail: Settling
                processingDate: '2023-12-14T22:45:50.9977213Z'
                refundedValue: 2500
                refundedToken: null
                message: null
                code: null
                connectorRefundedValue: 0
                cancelledValue: 0
      deprecated: false
  /api/pvt/transactions/{transactionId}/cancellation-request:
    post:
      tags:
      - Transaction Flow
      summary: VTex Cancel the transaction
      description: "Cancels a transaction that was previously approved, but not settled. It is possible to cancel partially or complete value of the transaction.\r\n\r\nDue to acquirer rules it is not possible to perform this step online against the acquirer.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| PCI Gateway | Payment-Make Payments | **Process payments** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
      operationId: Cancelthetransaction
      parameters:
      - $ref: '#/components/parameters/transactionId'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelthetransactionRequest'
            example:
              value: 2300
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettleResponse'
              example:
                id: null
                token: 2BCA48B4FBCB42D0B8A19EE965712AD8
                status: 13
                statusDetail: Finished
                processingDate: '2023-12-14T22:45:50.9977213Z'
                refundedValue: 0
                refundedToken: null
                message: null
                code: null
                connectorRefundedValue: 0
                cancelledValue: 74269
      deprecated: false
components:
  schemas:
    RefundthetransactionRequest:
      required:
      - value
      type: object
      description: Refund transaction request body information.
      properties:
        value:
          type: number
          description: Purchase value. The value must be described without using separation for decimals, e.g. to capture a value of 320.50, send 32050.
        freight:
          type: number
          description: Freigth value, if applicable.
        tax:
          type: number
          description: Tax value, if applicable.
        minicart:
          type: object
          description: This field is filled with the content of the cart of the transaction, which can be obtained using [Get Orders](https://developers.vtex.com/docs/api-reference/orders-api?endpoint=get-/api/oms/pvt/orders/-orderId-) or [Transaction Details](https://developers.vtex.com/docs/api-reference/payments-gateway-api?endpoint=get-/api/pvt/transactions/-transactionId-) endpoints. It should only be included for transactions with split payment.
          items:
            type: array
            description: Array containing cart items.
            items:
              type: object
              description: Cart items information.
              properties:
                id:
                  type: string
                  description: Item identifier.
                  example: '122323'
                name:
                  type: string
                  description: Item name.
                  example: Tenis Preto I
                value:
                  type: number
                  description: Item value.
                  example: 1000
                shippingDiscount:
                  type: integer
                  description: Discount to be applied for the shipping value.
                  example: 0
                discount:
                  type: integer
                  description: Discount applied on item.
                  example: 50
    CancelthetransactionRequest:
      required:
      - value
      type: object
      description: Cancel transaction request body information.
      properties:
        value:
          type: number
          description: Value of the purchase that will be cancelled.
    SettlethetransactionRequest:
      required:
      - value
      type: object
      description: Settle transaction request body information.
      properties:
        value:
          type: number
          description: Value to be settled. The value must be described without using separation for decimals, e.g. to capture a value of 320.50, send 32050.
          example: 10050
    SettleResponse:
      required:
      - id
      - token
      - status
      - statusDetail
      - processingDate
      - refundedValue
      - refundedToken
      - message
      - code
      - connectorRefundedValue
      - cancelledValue
      type: object
      description: ' Transaction response body information.'
      properties:
        id:
          type: string
          description: Settle request identification.
          nullable: true
        token:
          type: string
          description: Token identification.
        status:
          type: number
          description: Status code.
        statusDetail:
          type: string
          description: Status detail information.
        processingDate:
          type: string
          description: Settlement processing date.
        refundedValue:
          type: integer
          description: Refunded value.
        refundedToken:
          type: string
          description: Refund operation token.
          nullable: true
        message:
          type: string
          description: Custom message.
          nullable: true
        code:
          type: string
          description: Custom code.
          nullable: true
        connectorRefundedValue:
          type: number
          description: Refunded value by connector (provider).
        cancelledValue:
          type: integer
          description: Cancelled value.
  parameters:
    Accept:
      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
        example: application/json
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        example: application/json
    transactionId:
      name: transactionId
      in: path
      description: Transaction identification.
      required: true
      style: simple
      schema:
        type: string
        example: A3BDE325F76B4B758B398D900DF06150
  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.'