VTEX Installments API

openapi: 3.2.0
info:
  title: VTex Payments Gateway Installments 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: Installments
paths:
  /api/pvt/installments:
    get:
      tags:
      - Installments
      summary: VTex Get installments options
      description: 'Returns the best installment options according to the parameters informed in the request.


        ## 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 | **View Payment Data** |


        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: Installmentsoptions
      parameters:
      - name: request.value
        in: query
        description: Value to be divided into installments.
        required: true
        style: form
        schema:
          type: integer
          example: 10
      - name: request.salesChannel
        in: query
        description: Sales channel identification. Attribute created by the seller in their VTEX store configuration.
        required: false
        style: form
        schema:
          type: integer
          example: 1
      - name: request.paymentDetails[0].id
        in: query
        description: Payment system identification.
        required: false
        style: form
        schema:
          type: integer
          example: 2
      - name: request.paymentDetails[0].value
        in: query
        description: Total value paid in installments. If applied in the search, it must be equal to the `request.value` field.
        required: false
        style: form
        schema:
          type: integer
          example: 10
      - name: request.paymentDetails[0].bin
        in: query
        description: First six digits of the card number.
        required: false
        style: form
        schema:
          type: integer
          example: 411111
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidRequest'
              example:
                value: 250
                installments:
                - payment:
                    id: 72
                    name: null
                    bin: null
                    value: 250
                    isDefault: false
                    self:
                      href: /api/pvt/payment-systems/72
                  options:
                  - ruleId: 01a8d68b-9116-4655-83f8-3380f658ec04
                    quantity: 1
                    value: 250
                    interestRate: 0
                    isExternalInstallmentService: null
                    interestTax: 0
                  - ruleId: 01a8d68b-9116-4655-83f8-3380f658ec04
                    quantity: 2
                    value: 125
                    interestRate: 0
                    isExternalInstallmentService: null
                    interestTax: 0
                  - ruleId: 01a8d68b-9116-4655-83f8-3380f658ec04
                    quantity: 3
                    value: 83.33
                    interestRate: 0
                    isExternalInstallmentService: null
                    interestTax: 0
                  - ruleId: 01a8d68b-9116-4655-83f8-3380f658ec04
                    quantity: 4
                    value: 62.5
                    interestRate: 0
                    isExternalInstallmentService: null
                    interestTax: 0
                - payment:
                    id: 5
                    name: ERedeV2 - Visa
                    bin: null
                    value: 10
                    isDefault: false
                    self:
                      href: /api/pvt/payment-systems/2
                  options:
                  - ruleId: 993d4d35-b64d-454d-8108-c560580160e0
                    quantity: 1
                    value: 250
                    interestRate: 0
                    isExternalInstallmentService: null
                    interestTax: null
                - payment:
                    id: 12
                    name: PayPal - 6U0DTI3M3OKO6R
                    bin: null
                    value: 10
                    isDefault: false
                    self:
                      href: /api/pvt/payment-systems/12
                  options:
                  - ruleId: 9ac0fa1b-dd9d-4549-abb8-e73bbb63c280
                    quantity: 1
                    value: 250
                    interestRate: 0
                    isExternalInstallmentService: null
                    interestTax: null
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestValue'
              example:
                error:
                  code: '1'
                  message: Value must be greater than Zero
                  exception: null
      deprecated: false
components:
  schemas:
    Installment:
      required:
      - payment
      - options
      type: object
      description: Installment options information.
      properties:
        payment:
          $ref: '#/components/schemas/Payment'
        options:
          type: array
          description: Array containing information about installment options.
          items:
            $ref: '#/components/schemas/Option'
    InvalidRequestValue:
      required:
      - error
      type: object
      description: Installments options response body information.
      properties:
        error:
          required:
          - code
          - message
          - exception
          type: object
          description: Error information.
          properties:
            code:
              type: string
              description: Error code.
            message:
              type: string
              description: Error message.
            exception:
              type:
              - string
              - 'null'
              description: Exception information.
    Payment:
      required:
      - id
      - name
      - bin
      - value
      - isDefault
      - self
      type: object
      description: Payment system information.
      properties:
        id:
          type: integer
          description: Payment system identification.
        name:
          type:
          - string
          - 'null'
          description: Payment system name.
        bin:
          type:
          - string
          - 'null'
          description: First six digits of the card number.
        value:
          type: number
          description: Value to be paid in installments.
        isDefault:
          type: boolean
          description: Indicates whether the payment system is automatically applied by default.
          default: false
        self:
          $ref: '#/components/schemas/Self'
    Self:
      required:
      - href
      type: object
      description: Object containing the payment system reference route.
      properties:
        href:
          type: string
          description: Payment system reference route.
    ValidRequest:
      required:
      - value
      - installments
      type: object
      description: Installments options response body information.
      properties:
        value:
          type: number
          description: Value to be paid in installments.
        installments:
          type: array
          items:
            $ref: '#/components/schemas/Installment'
          description: Installments information.
    Option:
      required:
      - ruleId
      - quantity
      - value
      - interestRate
      - isExternalInstallmentService
      - interestTax
      type: object
      description: Installment options information.
      properties:
        ruleId:
          type:
          - string
          - 'null'
          description: Rule identification.
        quantity:
          type: integer
          description: Number of installments.
        value:
          type: number
          description: Value of each installment.
        interestRate:
          type: number
          description: Interest rate (percent 0.1 = 10%).
        isExternalInstallmentService:
          type:
          - number
          - 'null'
          description: Indicates the external installment system (if applicable).
        interestTax:
          type:
          - number
          - 'null'
          description: Interest tax (percent 0.1 = 10%).
  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
  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.'