openapi: 3.0.0
info:
  title: Balances API
  description: REST 2.0 Balances API
  version: 2.5.1
servers:
  - url: https://api-sandbox.nuvei.com/balance-api
    description: sandbox
  - url: https://api.nuvei.com/balance-api
    description: prod
tags:
  - name: Balances
paths:
  /pix/entities/{entity-id}/balances:
    get:
      tags:
        - Balances
      summary: Retrieve Merchant Balances
      description: Retrieves a merchant's balances from all PIX providers.
      operationId: getBalances
      parameters:
        - name: entity-id
          in: path
          required: true
          style: simple
          explode: false
          schema:
            maxLength: 50
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
      security:
        - apiKeyAuth: []
  /pix/entities/{entity-id}/closing-balances/{report-date}:
    get:
      tags:
        - Balances
      summary: Retrieve Merchant Balances at the end of the specified date
      description: Retrieves a merchant's balances from all PIX providers at the end of the specified date.
      operationId: getClosingBalances
      parameters:
        - name: entity-id
          in: path
          required: true
          style: simple
          explode: false
          schema:
            maxLength: 50
            type: string
        - name: report-date
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
            format: date
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
      security:
        - apiKeyAuth: []
components:
  schemas:
    Provider:
      type: string
      enum:
        - P1
        - P2
        - P3
        - P4
        - P5
        - P6
    Amount:
      type: number
    Currency:
      maxLength: 3
      minLength: 3
      type: string
      default: BRL
    Balance:
      required:
        - provider
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/Provider'
        accountId:
          $ref: '#/components/schemas/AccountId'
        amount:
          $ref: '#/components/schemas/Amount'
        currency:
          $ref: '#/components/schemas/Currency'
        lastUpdated:
          type: string
          format: date-time
    BalanceItem:
      allOf:
        - $ref: '#/components/schemas/Balance'
        - $ref: '#/components/schemas/BaseApiResultOutput'
    Balances:
      type: object
      properties:
        balances:
          type: array
          items:
            required:
              - provider
              - status
            type: object
            properties:
              provider:
                $ref: '#/components/schemas/Provider'
              accountId:
                $ref: '#/components/schemas/AccountId'
              amount:
                $ref: '#/components/schemas/Amount'
              currency:
                $ref: '#/components/schemas/Currency'
              lastUpdated:
                type: string
                format: date-time
              status:
                $ref: '#/components/schemas/BaseResultStatus'
              errors:
                $ref: '#/components/schemas/ResultError'
    AccountId:
      type: string
    BalancesResponse:
      allOf:
        - $ref: '#/components/schemas/Balances'
        - $ref: '#/components/schemas/BaseApiResponse'
    BaseApiResponse:
      required:
        - result
      type: object
      properties:
        result:
          $ref: '#/components/schemas/BaseApiResultOutput'
    BaseApiResultOutput:
      required:
        - status
      type: object
      properties:
        status:
          $ref: '#/components/schemas/BaseResultStatus'
        errors:
          $ref: '#/components/schemas/ResultError'
    BaseResultStatus:
      type: string
      description: 'Status of the request: success | error'
      enum:
        - success
        - error
    ResultError:
      required:
        - code
      type: object
      properties:
        code:
          maxLength: 11
          type: string
          description: If an error occurred on the request side, an error code is returned in this parameter.
          example: '7000.1000'
        reason:
          maxLength: 400
          type: string
          description: If an error occurred on the request side, then an error reason is returned in this parameter.
          example: Internal Processing Error
        reference:
          maxLength: 400
          type: string
          description: Reference value for troubleshooting
          example: '110.1260'
      description: If an error occurred on the request side, an error code is returned in this parameter.
  parameters:
    entity-id:
      name: entity-id
      in: path
      required: true
      style: simple
      explode: false
      schema:
        maxLength: 50
        type: string
    provider-id:
      name: provider-id
      in: path
      required: true
      style: simple
      explode: false
      schema:
        $ref: '#/components/schemas/Provider'
    report-date:
      name: report-date
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type: string
        format: date
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: X-API-KEY
      in: header