VTEX Payment API

openapi: 3.2.0
info:
  title: Vtex Payment API
  version: '1.0'
  contact: {}
  description: 'Operations tagged Payment across 2 of this provider''s published API definitions: vtex-orders-openapi-original.yml, vtex-orders-pii-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{accountName}.{environment}.com.br
  description: VTEX server URL.
  variables:
    accountName:
      description: Name of the VTEX account. Used as part of the URL.
      default: apiexamples
    environment:
      description: Environment to use. Used as part of the URL.
      enum:
      - vtexcommercestable
      default: vtexcommercestable
security:
- appKey:
  - '{{appKey}}'
  appToken:
  - '{{appToken}}'
tags:
- name: Payment
paths:
  /api/oms/pvt/orders/{orderId}/payment-transaction:
    get:
      tags:
      - Payment
      summary: VTex Retrieve payment transaction
      description: "Retrieves transaction details by order ID. All events in the transaction will be registered in this call's response body. \n\nIn scenarios of [order changes](https://developers.vtex.com/vtex-rest-api/reference/registerchange), it is possible to insert a [Partial invoice](https://help.vtex.com/en/tracks/pedidos--2xkTisx4SXOWXQel8Jg8sa/q9GPspTb9cHlMeAZfdEUe). The total value of the order will be updated after the insertion of the invoice, even when there is a [Partial invoice](https://help.vtex.com/en/tracks/pedidos--2xkTisx4SXOWXQel8Jg8sa/q9GPspTb9cHlMeAZfdEUe) scenario. The updated value is settled by VTEX's Payment Gateway. The reimbursement for the shopper is automatic."
      operationId: GetPaymenttransaction
      parameters:
      - 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: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: orderId
        in: path
        description: Order ID is a unique code that identifies an order.
        example: 1172452900788-01
        required: true
        style: simple
        schema:
          type: string
          example: 1172452900788-01
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymenttransaction'
              example:
                status: Finished
                isActive: true
                transactionId: CB452D77E7D04099A4DB0479087B1D2C
                merchantName: LUXSTORE
                payments:
                - id: 721CBE1090324D12ABE301FE33DE775A
                  paymentSystem: '4'
                  paymentSystemName: Mastercard
                  value: 10150
                  installments: 1
                  referenceValue: 10150
                  cardHolder: null
                  cardNumber: null
                  firstDigits: '412341'
                  lastDigits: '4123'
                  url: null
                  giftCardId: null
                  giftCardName: null
                  cvv2: null
                  expireMonth: null
                  expireYear: null
                  giftCardCaption: null
                  redemptionCode: null
                  group: creditCard
                  tid: '101770752'
                  dueDate: null
                  connectorResponses:
                    Tid: '101770752'
                    ReturnCode: '200'
                    Message: logMessage
                    authId: '170852'
      deprecated: false
    servers:
    - url: https://{accountName}.{environment}.com.br
      description: VTEX server URL.
      variables:
        accountName:
          description: Name of the VTEX account. Used as part of the URL.
          default: apiexamples
        environment:
          description: Environment to use. Used as part of the URL.
          enum:
          - vtexcommercestable
          default: vtexcommercestable
  /api/oms/pvt/orders/{orderId}/payments/{paymentId}/payment-notification:
    post:
      tags:
      - Payment
      summary: VTex Send payment notification
      description: 'Send a payment notification of a given order, by order ID.


        > The `Notify payment` resource is needed to use this API request. This is included in `OMS - Full access` and `IntegrationProfile - Fulfillment Oms`, among other default roles available in the Admin. Learn more about the [License manager roles and resources](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#).'
      operationId: SendPaymentNotification
      parameters:
      - 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: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: orderId
        in: path
        description: Order ID is a unique code that identifies an order.
        example: 1172452900788-01
        required: true
        style: simple
        schema:
          type: string
          example: 1172452900788-01
      - name: paymentId
        in: path
        description: VTEX payment identifier.
        example: F5C1A4E20D3B4E07B7E871F5B5BC9F91
        required: true
        style: simple
        schema:
          type: string
          example: F5C1A4E20D3B4E07B7E871F5B5BC9F91
      responses:
        '200':
          description: OK
        '400':
          description: Bad request.
        '403':
          description: The credentials are not enabled to access the service.
        '404':
          description: Value not found.
        '429':
          description: Too many requests.
      deprecated: false
    servers:
    - url: https://{accountName}.{environment}.com.br
      description: VTEX server URL.
      variables:
        accountName:
          description: Name of the VTEX account. Used as part of the URL.
          default: apiexamples
        environment:
          description: Environment to use. Used as part of the URL.
          enum:
          - vtexcommercestable
          default: vtexcommercestable
  /api/orders/pvt/document/{orderId}/payment/{paymentId}/notify-payment:
    post:
      tags:
      - Payment
      summary: VTex Send payment notification
      description: 'Send a payment notification of a given order, by order ID and payment ID.


        > The `Notify payment` resource is needed to use this API request. This is included in `OMS - Full access` and `IntegrationProfile - Fulfillment Oms`, among other default roles available in the Admin. Learn more about the [License manager roles and resources](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#).


        > Learn more about [Transaction Details](https://help.vtex.com/en/tutorial/how-to-view-the-orders-details).



        ## Request body properties


        | Attribute    | Type        | Description |

        | --------------- |:---------:| --------------------------------------:|

        | `orderId` | string | Order Id |

        | `paymentId` | string | Payment ID |'
      operationId: SendPaymentNotification2
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/orderId'
      - $ref: '#/components/parameters/paymentId'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '429':
          description: Too Many Requests
      deprecated: false
    servers:
    - url: https://{accountName}.{environment}.com.br
      description: VTEX server URL.
      variables:
        accountName:
          description: Name of the VTEX account. Used as part of the URL.
          default: apiexamples
        environment:
          description: Environment to use. Used as part of the URL.
          enum:
          - vtexcommercestable
          default: vtexcommercestable
components:
  schemas:
    ConnectorResponses:
      title: ConnectorResponses
      required:
      - Tid
      - ReturnCode
      - Message
      - authId
      type: object
      properties:
        Tid:
          type: string
          description: Connector transaction ID.
        ReturnCode:
          type:
          - string
          - 'null'
          description: Connector return code.
        Message:
          type:
          - string
          - 'null'
          description: Information about the connector's responses.
        authId:
          type: string
          description: Connector authorization ID.
      example:
        Tid: '101770752'
        ReturnCode: null
        Message: null
        authId: '170852'
    Payment1:
      title: Payment1
      required:
      - id
      - paymentSystem
      - paymentSystemName
      - value
      - installments
      - referenceValue
      - cardHolder
      - cardNumber
      - firstDigits
      - lastDigits
      - cvv2
      - expireMonth
      - expireYear
      - url
      - giftCardId
      - giftCardName
      - giftCardCaption
      - redemptionCode
      - group
      - tid
      - dueDate
      - connectorResponses
      type: object
      properties:
        id:
          type: string
          description: Payment ID.
        paymentSystem:
          type: string
          description: Payment system ID.
        paymentSystemName:
          type: string
          description: Payment system name.
        value:
          type: integer
          description: Payment value.
        installments:
          type: integer
          description: Payment Installments quantity.
        referenceValue:
          type: integer
          description: Payment reference Value.
        cardHolder:
          type:
          - string
          - 'null'
          description: Payment card holder.
        cardNumber:
          type:
          - string
          - 'null'
          description: Payment card number.
        firstDigits:
          type: string
          description: Payment card first digits.
        lastDigits:
          type: string
          description: Payment card last digits.
        cvv2:
          type:
          - string
          - 'null'
          description: Card Verification Value (CVV2) is a security code used by payment processors to reduce fraudulent credit and debit card transactions.
        expireMonth:
          type:
          - string
          - 'null'
          description: Payment card expire month.
        expireYear:
          type:
          - string
          - 'null'
          description: Payment card expire year.
        url:
          type:
          - string
          - 'null'
          description: Payment URL.
        giftCardId:
          type:
          - string
          - 'null'
          description: Gift Card ID.
        giftCardName:
          type:
          - string
          - 'null'
          description: Gift Card name.
        giftCardCaption:
          type:
          - string
          - 'null'
          description: Gift Card caption.
        redemptionCode:
          type:
          - string
          - 'null'
          description: Code for the customer to use the Gift Card.
        group:
          type: string
          description: "It represents the payment method. For each method, it can have the following values: \n\n- **Credit card:** `creditCard` \n\n- **Debid card:** `debitCard`\n\n- **Bank invoice:** `bankInvoice`\n\n- **Promissory:** `promissory` \n\n- **Gift card:** `giftCard` \n\n- **Pix:** `instantPayment`."
        tid:
          type: string
          description: Payment transaction ID.
        dueDate:
          type:
          - string
          - 'null'
          description: Payment due date.
        connectorResponses:
          $ref: '#/components/schemas/ConnectorResponses'
      example:
        id: 721CBE1090324D12ABE301FE33DE775A
        paymentSystem: '4'
        paymentSystemName: Mastercard
        value: 10150
        installments: 1
        referenceValue: 10150
        cardHolder: null
        cardNumber: null
        firstDigits: '412341'
        lastDigits: '4123'
        cvv2: null
        expireMonth: null
        expireYear: null
        url: null
        giftCardId: null
        giftCardName: null
        giftCardCaption: null
        redemptionCode: null
        group: creditCard
        tid: '101770752'
        dueDate: null
        connectorResponses:
          Tid: '101770752'
          ReturnCode: '200'
          Message: logMessage
          authId: '170852'
    GetPaymenttransaction:
      title: GetPaymenttransaction
      required:
      - status
      - isActive
      - transactionId
      - merchantName
      - payments
      type: object
      properties:
        status:
          type: string
          description: Transaction status.
        isActive:
          type: boolean
          description: If it is an active transaction (`true`) or not (`false`).
        transactionId:
          type: string
          description: Transaction ID.
        merchantName:
          type: string
          description: Transaction merchant's name.
        payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment1'
          description: Payments' details object.
      example:
        status: Finished
        isActive: true
        transactionId: CB452D77E7D04099A4DB0479087B1D2C
        merchantName: LUXSTORE
        payments:
        - id: 721CBE1090324D12ABE301FE33DE775A
          paymentSystem: '4'
          paymentSystemName: Mastercard
          value: 10150
          installments: 1
          referenceValue: 10150
          cardHolder: null
          cardNumber: null
          firstDigits: '412341'
          lastDigits: '4123'
          cvv2: null
          expireMonth: null
          expireYear: null
          url: null
          giftCardId: null
          giftCardName: null
          giftCardCaption: null
          redemptionCode: null
          group: creditCard
          tid: '101770752'
          dueDate: null
          connectorResponses:
            Tid: '101770752'
            ReturnCode: '200'
            Message: logMessage
            authId: '170852'
  parameters:
    orderId:
      name: orderId
      in: path
      description: ID of the order.
      required: true
      style: simple
      schema:
        type: string
        example: 70caf3941s6df1
    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
    paymentId:
      name: paymentId
      in: path
      description: ID of the payment.
      required: true
      style: simple
      schema:
        type: string
        example: 45hsfg5jkyu1384jdsfgh654sfgj1
    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
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken
    VtexIdclientAutCookie:
      type: apiKey
      in: header
      name: VtexIdclientAutCookie
x-refined-from:
- vtex-orders-openapi-original.yml
- vtex-orders-pii-openapi-original.yml