VTEX Transaction Flow API

openapi: 3.2.0
info:
  title: VTex Payments Gateway Transaction Flow API
  description: '>ℹ️ Onboarding guide

    >

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


    The Payments Gateway API allows you to get payment data and process your store''s transactions.


    ## Payments Gateway API Index


    ### Installments


    - `GET` [Get installments options](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/installments)


    ### Configuration


    - `GET` [List all affiliations](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/affiliations)

    - `POST` [Insert a new affiliation](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/affiliations)

    - `PUT` [Update affiliation by ID](https://developers.vtex.com/docs/api-reference/payments-gateway-api#put-/api/pvt/affiliations/-affiliationId-)

    - `GET` [Get affiliation by ID](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/affiliations/-affiliationId-)

    - `GET` [List all payment rules](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/rules)

    - `POST` [Insert a new payment rule](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/rules)

    - `GET` [Get payment rule by ID](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/rules/-ruleId-)

    - `PUT` [Update payment rule by ID](https://developers.vtex.com/docs/api-reference/payments-gateway-api#put-/api/pvt/rules/-ruleId-)

    - `DELETE` [Delete payment rule by ID](https://developers.vtex.com/docs/api-reference/payments-gateway-api#delete-/api/pvt/rules/-ruleId-)

    - `GET` [List all available payment methods](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/merchants/payment-systems)


    ### Transaction Process


    - `POST` [1. Starts a new transaction](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions)

    - `POST` [2.1 Send payments information public](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pub/transactions/-transactionId-/payments)

    - `POST` [2.2 Send payments with saved credit card](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions/-transactionId-/payments)

    - `POST` [3. Send additional data](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions/-transactionId-/additional-data)

    - `PATCH` [3.1 Update additional data (optional)](https://developers.vtex.com/docs/api-reference/payments-gateway-api#patch-/api/pvt/transactions/-transactionId-/additional-data)

    - `POST` [Authorize new transaction](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions/-transactionId-/authorization-request)

    - `GET` [Get transaction details](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/transactions/-transactionId-)

    - `GET` [Get payment details](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/transactions/-transactionId-/payments/-paymentId-)

    - `GET` [Get transaction settlement details](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/transactions/-transactionId-/settlements)


    ### Transaction Flow


    - `POST` [Settle the transaction](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions/-transactionId-/settlement-request)

    - `POST` [Refund the transaction](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions/-transactionId-/refunding-request)

    - `POST` [Cancel the transaction](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions/-transactionId-/cancellation-request)'
  version: '1.0'
servers:
- url: https://{accountName}.vtexpayments.com.br
  description: VTEX server URL.
  variables:
    accountName:
      description: Name of the VTEX account. Used as part of the URL.
      default: apiexamples
security:
- appKey: []
  appToken: []
- VtexIdclientAutCookie: []
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.


        >ℹ️ This call is mandatory to complete a transaction and its payments.


        ## Permissions


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


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

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

        | PCI Gateway | Payment-Make Payments | **Process payments** |


        There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).


        >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.'
      operationId: 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.


        After a transaction is settled, this request can be used to partially or fully refund the transaction amount.


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


        ## Permissions


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


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

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

        | PCI Gateway | Payment-Make Payments | **Process payments** |


        There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).


        >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.'
      operationId: 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.


        Due to acquirer rules it is not possible to perform this step online against the acquirer.


        ## Permissions


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


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

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

        | PCI Gateway | Payment-Make Payments | **Process payments** |


        There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).


        >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.'
      operationId: 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:
    CancelthetransactionRequest:
      required:
      - value
      type: object
      description: Cancel transaction request body information.
      properties:
        value:
          type: number
          description: Value of the purchase that will be cancelled.
    SettleResponse:
      required:
      - id
      - token
      - status
      - statusDetail
      - processingDate
      - refundedValue
      - refundedToken
      - message
      - code
      - connectorRefundedValue
      - cancelledValue
      type: object
      description: ' Transaction response body information.'
      properties:
        id:
          type:
          - string
          - 'null'
          description: Settle request identification.
        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
          - 'null'
          description: Refund operation token.
        message:
          type:
          - string
          - 'null'
          description: Custom message.
        code:
          type:
          - string
          - 'null'
          description: Custom code.
        connectorRefundedValue:
          type: number
          description: Refunded value by connector (provider).
        cancelledValue:
          type: integer
          description: Cancelled value.
    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
    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
  parameters:
    transactionId:
      name: transactionId
      in: path
      description: Transaction identification.
      required: true
      style: simple
      schema:
        type: string
        example: A3BDE325F76B4B758B398D900DF06150
    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
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
      description: Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken
      description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    VtexIdclientAutCookie:
      type: apiKey
      in: header
      name: VtexIdclientAutCookie
      description: '[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.'