VTEX Installments API

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

    >

    > Check the new Payments onboarding guide.'
  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 must have at least one of the appropriate License Manager resources 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 for this resource list. You must create a custom 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.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys 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:
  parameters:
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        example: application/json
    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
  schemas:
    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.
    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.
    Self:
      required:
      - href
      type: object
      description: Object containing the payment system reference route.
      properties:
        href:
          type: string
          description: Payment system reference route.
    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'
    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%).
  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.'