openapi: 3.1.0
info:
  title: API de Débito Direto da Belvo
  version: 1.0.0
  description: >-
    Nossa infraestrutura de pagamento tem como objetivo facilitar, acelerar e
    modular a movimentação de dinheiro entre empresas e pessoas.
  contact:
    name: Need help?
    url: https://developers.belvo.com
    email: support@belvo.com
servers:
  - url: https://api.sandbox.directdebit.belvo.com
security:
  - ApiKeyAuth: []
    ApiKeySecret: []
tags:
  - name: Institutions (Direct Debit Mexico)
    description: >-
      Use o recurso Institutions para: listar todas as instituições para as
      quais você pode fazer pagamentos e de onde pode recebê-los.
  - name: Customers (Direct Debit Mexico)
    description: >-
      Um Cliente é o usuário final, seja um indivíduo ou uma empresa, que possui
      a conta bancária envolvida em uma operação de débito ou pagamento. O Belvo
      Direct Debit armazena as informações essenciais deste Cliente para
      simplificar e reutilizá-las em vários métodos de pagamento e destinos de
      pagamento.
  - name: Payment Methods (Direct Debit Mexico)
    description: >-
      Um Método de Pagamento contém os detalhes da conta bancária de origem da
      qual você debitará os fundos.
  - name: Payment Requests (Direct Debit Mexico)
    description: >-
      Uma Solicitação de Pagamento é a transação real que você deseja executar
      para debitar fundos de uma conta. Cada Solicitação de Pagamento deve estar
      associada a um Método de Pagamento previamente criado. Para cada nova
      transação que você deseja realizar, é necessário criar uma nova
      Solicitação de Pagamento.
  - name: Movements (Direct Debit Mexico)
    description: >-
      Use o recurso Movements para listar todos os Movements da conta
      (transações que ocorrem dentro da sua conta bancária).
  - name: Payment Consents (Direct Debit Mexico)
    description: >-
      Um Consentimento em Débito Direto é a prova de que seu cliente confirmou
      que terá fundos debitados de sua conta (Método de Pagamento). Essa prova é
      composta por fotos do documento de identidade, uma selfie e um contrato
      assinado.
paths:
  /customers:
    post:
      summary: Criar um cliente
      description: Criar um novo cliente de Débito Direto
      operationId: CreateDirectDebitCustomer
      tags:
        - Customers (Direct Debit Mexico)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_customer_individual'
      responses:
        '201':
          description: Criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerId'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /customers/:
    get:
      summary: Listar todos os clientes
      description: Liste todos os clientes de Débito Direto associados à sua conta.
      operationId: ListDirectDebitCustomers
      tags:
        - Customers (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/search_customer'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customers_paginated'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /customers/{customerId}:
    post:
      summary: Atualizar um cliente
      description: Atualizar um cliente de débito direto existente
      operationId: UpdateDirectDebitCustomer
      tags:
        - Customers (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/customerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_customer_individual'
      responses:
        '201':
          description: Criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerId'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
    get:
      summary: Obter os detalhes de um cliente
      description: Obtenha os detalhes sobre um cliente específico de débito direto.
      operationId: DetailDirectDebitCustomer
      tags:
        - Customers (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/customerId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer_individual'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /institutions:
    get:
      summary: Listar todas as instituições
      description: Liste todas as instituições disponíveis.
      operationId: ListDirectDebitInstitutions
      tags:
        - Institutions (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/institutions'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /payment_methods/bank_accounts:
    post:
      summary: Criar um método de pagamento
      description: Criar um novo método de pagamento para um cliente
      operationId: CreateDirectDebitPaymentMethod
      tags:
        - Payment Methods (Direct Debit Mexico)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_payment_method'
      responses:
        '201':
          description: Criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paymentMethodId'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /payment_methods:
    get:
      summary: Liste todos os métodos de pagamento
      description: Liste todos os métodos de pagamento associados à sua conta.
      operationId: ListDirectDebitPaymentMethods
      tags:
        - Payment Methods (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/search__general'
        - $ref: '#/components/parameters/customer_id'
        - $ref: '#/components/parameters/type'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method_paginated'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /payment_methods/{paymentMethodId}:
    get:
      summary: Obter os detalhes de um método de pagamento
      description: Obtenha os detalhes sobre um método de pagamento específico.
      operationId: DetailDirectDebitPaymentMethod
      tags:
        - Payment Methods (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/paymentMethodId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /payment_methods/{paymentMethodId}/deactivate:
    post:
      summary: Desativar um método de pagamento
      description: >-
        Desativar um método de pagamento específico.


        > 📘 Informações

        >

        > Você só pode desativar um método de pagamento quando o `status`
        estiver no estado `active` e não houver solicitações de pagamento
        pendentes (`paymentRequest.status` = `processing`).
      operationId: DeactivateDirectDebitPaymentMethod
      tags:
        - Payment Methods (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/paymentMethodId'
      responses:
        '201':
          description: Criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /payment_requests:
    post:
      summary: Criar uma solicitação de pagamento
      description: >-
        Crie uma nova solicitação de pagamento para um método de pagamento
        existente.


        > 📘 Chaves de Idempotência

        >

        > Este método suporta chaves de idempotência.
      operationId: CreateDirectDebitPaymentRequest
      tags:
        - Payment Requests (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/idempotency_key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_payment_request_existing'
      responses:
        '201':
          description: Solicitação de Pagamento Criada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paymentRequestId'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
    get:
      summary: Listar todas as solicitações de pagamento
      description: Liste todas as solicitações de pagamento associadas à sua conta.
      operationId: ListDirectDebitPaymentRequests
      tags:
        - Payment Requests (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/search__general'
        - $ref: '#/components/parameters/customer_id'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/start_date'
        - $ref: '#/components/parameters/end_date'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_request_paginated'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /payment_requests/{paymentRequestId}:
    get:
      summary: Obter os detalhes de uma solicitação de pagamento
      description: Obtenha os detalhes sobre uma solicitação de pagamento específica.
      operationId: DetailDirectDebitPaymentRequest
      tags:
        - Payment Requests (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/paymentRequestId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_request'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /payment_requests/{paymentRequestId}/cancel:
    post:
      summary: Cancelar uma solicitação de pagamento
      description: >-
        Cancelar uma solicitação de pagamento.


        > 📘 Informações

        >

        > Você só pode cancelar uma solicitação de pagamento quando o `status`
        estiver no estado `initial`.
      operationId: CancelDirectDebitPaymentRequest
      tags:
        - Payment Requests (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/paymentRequestId'
      responses:
        '201':
          description: Criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_request'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /account_movements:
    get:
      summary: Obtenha os movimentos da sua conta
      description: Obtenha um extrato dos movimentos que ocorreram em sua conta.
      operationId: ListDirectDebitAccountMovements
      tags:
        - Movements (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/from_created_date'
        - $ref: '#/components/parameters/until_created_date'
        - $ref: '#/components/parameters/type_movement'
        - $ref: '#/components/parameters/withdrawal_id'
        - $ref: '#/components/parameters/reason'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/movement_paginated'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /consents:
    post:
      summary: Criar um Consentimento
      description: >-
        Crie o Consentimento inicial para um Método de Pagamento. Após criar um
        Consentimento, você pode enviar documentos de suporte que servem como
        consentimento do seu cliente para debitar a conta bancária dele usando o
        endpoint Upload Consent Files.
      operationId: CreateConsent
      tags:
        - Payment Consents (Direct Debit Mexico)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - paymentMethodId
              properties:
                paymentMethodId:
                  type: string
                  format: uuid
                  description: >-
                    O identificador único criado pela Belvo usado para
                    referenciar o método de pagamento para o qual você deseja
                    enviar documentos de consentimento.
                  example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
      responses:
        '201':
          description: Consentimento Criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/consent'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
    get:
      summary: Listar todos os Consents
      description: >-
        Liste todos os Consentimentos que você criou para seus Métodos de
        Pagamento.
      operationId: ListAllConsents
      tags:
        - Payment Consents (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Lista de Consentimentos
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                  - metadata
                  - links
                properties:
                  items:
                    type: array
                    description: Um array de objetos de consentimento.
                    items:
                      $ref: '#/components/schemas/consent'
                  metadata:
                    $ref: '#/components/schemas/paginated_meta'
                  links:
                    $ref: '#/components/schemas/paginated_links'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /consents/{consentId}:
    get:
      summary: Obter os Detalhes de um Consentimento
      operationId: GetConsentDetails
      description: Obtenha os detalhes de um consentimento específico.
      tags:
        - Payment Consents (Direct Debit Mexico)
      parameters:
        - name: consentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: O ID do consentimento para o qual você deseja obter detalhes.
      responses:
        '200':
          description: Detalhes do Consentimento
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/consent'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /consents/{consentId}/files:
    post:
      summary: Fazer Upload de Arquivos de Consentimento
      description: >-
        Envie arquivos que sirvam como consentimento do seu cliente para debitar
        a conta bancária dele. Você deve enviar todos os arquivos necessários
        para um Consentimento (scans frente e verso do documento de identidade,
        uma selfie do usuário segurando o documento de identidade e um contrato
        assinado). Cada arquivo não pode ter mais de 20MB.
      operationId: UploadConsentFiles
      tags:
        - Payment Consents (Direct Debit Mexico)
      parameters:
        - name: consentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: O ID do Consentimento para o qual você deseja enviar arquivos.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - id_front
                - id_back
                - selfie
                - contract
              description: >-
                Os arquivos para upload do Consentimento. Cada arquivo não pode
                ter mais de 20MB.
              properties:
                id_front:
                  type: string
                  format: binary
                  description: >-
                    A foto/escaneamento frontal do documento de identidade do
                    usuário.
                id_back:
                  type: string
                  format: binary
                  description: >-
                    A parte traseira escaneada/foto do documento de identidade
                    do usuário.
                selfie:
                  type: string
                  format: binary
                  description: Uma selfie do usuário segurando seu documento de identidade.
                contract:
                  type: string
                  format: binary
                  description: Um contrato assinado pelo usuário autorizando o débito.
      responses:
        '201':
          description: Arquivos de Consentimento Carregados
          content:
            application/json:
              schema:
                type: array
                description: >-
                  Um array de objetos de arquivo de Consent que foram
                  carregados.
                items:
                  $ref: '#/components/schemas/consent_id_file'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
    get:
      summary: Obter os Arquivos de um Consentimento
      description: >-
        Liste todos os arquivos que foram enviados para um Consentimento
        específico.
      operationId: ListConsentFiles
      tags:
        - Payment Consents (Direct Debit Mexico)
      parameters:
        - name: consentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: O ID do Consentimento para o qual você deseja obter arquivos.
      responses:
        '200':
          description: Lista de Arquivos
          content:
            application/json:
              schema:
                type: array
                description: Um array de objetos de arquivo Consent.
                items:
                  $ref: '#/components/schemas/consent_id_file'
        '400':
          description: Solicitação Inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: Não autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: Não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api-key-id
    ApiKeySecret:
      type: apiKey
      in: header
      name: api-key-secret
  schemas:
    documentType_individual:
      type: string
      title: Individual
      enum:
        - mx_rfc
        - mx_curp
      description: |-
        O tipo de documento do indivíduo.

        Para 🇲🇽 México, pode ser um dos seguintes:
          - `mx_rfc`: Número de Identificação Fiscal (*Registro Federal de Contribuyentes*)
          - `mx_curp`: Código Único de Registro de População (*Clave Única de Registro de Población*)
      example: mx_rfc
    create_customer_individual:
      type: object
      title: Individual
      description: Corpo da solicitação para criar um cliente de débito direto.
      required:
        - firstname
        - lastname
        - email
        - documentType
        - documentNumber
      properties:
        firstname:
          type: string
          minLength: 1
          maxLength: 50
          description: O primeiro nome do cliente.
          example: Carlos
        lastname:
          type: string
          minLength: 1
          maxLength: 50
          description: O sobrenome do cliente.
          example: Vives
        email:
          type: string
          format: email
          description: O email do cliente.
          example: carlos-vives@musica.mx
        documentType:
          $ref: '#/components/schemas/documentType_individual'
        documentNumber:
          type: string
          description: >-
            O número do documento do cliente.  

            Para o México, deve ter 18 caracteres.


            > **Nota**: Se o `documentNumber` não corresponder ao comprimento e
            formato de caracteres esperados para um determinado `documentType`,
            retornamos um erro `400 input_validation`.
          example: '123456789'
        phone:
          type: string
          description: O número de telefone do cliente (incluindo o código do país).
          example: '+523001234567'
    customerId:
      type: object
      properties:
        customerId:
          type: string
          format: uuid
          readOnly: true
          description: >-
            O identificador único criado pela Belvo usado para referenciar o
            cliente.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    400_bad_request_error:
      type: object
      title: Solicitação Inválida
      description: >-
        Esse erro ocorre quando os parâmetros fornecidos não correspondem aos
        campos esperados ou o item que você está tentando criar já está em nosso
        banco de dados.
      properties:
        statusCode:
          type: integer
          description: O código de status HTTP para este erro.
          example: 400
        error:
          type: string
          description: A descrição do código de status HTTP para este erro.
          example: Bad Request
        message:
          oneOf:
            - type: string
              title: String Única
            - type: array
              title: Array de Strings
              items:
                type: string
          description: >-
            Uma breve descrição do erro, indicando o que está errado com a
            solicitação.

            > **Nota**: Retornamos uma string ou um array de strings, dependendo
            do(s) erro(s) de validação.


            A descrição pode ser (entre outras):

              - `id must be a UUID`
              - `Not enough balance`
              - `amount is not a valid decimal number.`
              - `currency must be one of the following values: cop, mxn, usd`
              - `reference must be a string`
              - `Customer not found for merchant`
              - `documentType is a required field`
          example: id must be a UUID
    401_unauthorized_error:
      type: object
      title: Não autorizado
      description: >-
        Esse erro ocorre quando você tenta fazer uma chamada de API usando
        credenciais incorretas da API Belvo (ou sua chave secreta ou senha
        secreta, ou ambos, estão incorretos).
      properties:
        statusCode:
          type: integer
          description: O código de status HTTP para este erro.
          example: 401
        error:
          type: string
          description: A descrição do código de status HTTP para este erro.
          example: Unauthorized
        message:
          type: string
          description: >-
            Uma breve descrição do erro, indicando o que está errado com a
            solicitação. No caso de um erro 401 Unauthorized, a mensagem é:

              - `Unauthorized credentials`
          example: Unauthorized credentials
    404_not_found_error:
      type: object
      title: Não encontrado
      properties:
        statusCode:
          type: integer
          description: O código de status HTTP para este erro.
          example: 404
        error:
          type: string
          description: A descrição do código de status HTTP para este erro.
          example: Not Found
        message:
          type: string
          description: >-
            Uma breve descrição do erro, indicando o que está errado com a
            solicitação. A descrição pode ser (entre outras):

              - `Payout Target not found`
              - `Payment method not found`
              - `Customer not found`
          example: Payout Target not found
    customer_individual:
      type: object
      title: Individual
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: >-
            O identificador único criado pela Belvo usado para referenciar o
            cliente.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        createdDate:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: >-
            O timestamp ISO-8601 quando o cliente foi criado no banco de dados
            da Belvo.
          example: '2022-02-09T08:45:50.406032Z'
        lastUpdatedDate:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: >-
            O carimbo de data e hora ISO-8601 quando as informações sobre o
            cliente foram atualizadas pela última vez.
          example: '2022-02-09T08:45:50.406032Z'
        firstname:
          type: string
          minLength: 1
          maxLength: 50
          description: O primeiro nome do cliente.
          example: Carlos
        lastname:
          type: string
          minLength: 1
          maxLength: 50
          description: O sobrenome do cliente.
          example: Vives
        email:
          type: string
          format: email
          description: O email do cliente.
          example: carlos-vives@musica.mx
        phone:
          type: string
          description: O número de telefone do cliente (incluindo o código do país).
          example: '+523001234567'
        country:
          type: string
          pattern: ^[a-z]{3}$
          description: >-
            O código de três letras do país do cliente conforme a norma ISO
            3166-1 alpha-3.
          example: mex
        documentType:
          $ref: '#/components/schemas/documentType_individual'
        documentNumber:
          type: string
          description: O número do documento do cliente.
          example: '123456789'
    paginated_meta:
      type: object
      description: Metadados adicionais sobre o conjunto de resultados paginados.
      properties:
        totalItems:
          type: integer
          format: int32
          description: O número total de itens no conjunto de resultados paginados.
          example: 100
        itemCount:
          type: integer
          format: int32
          description: O número de itens na página atual.
          example: 10
        itemsPerPage:
          type: integer
          format: int32
          description: O número de itens solicitados por página.
          example: 10
        totalPages:
          type: integer
          format: int32
          description: O número total de páginas no conjunto de resultados paginados.
          example: 10
        currentPage:
          type: integer
          format: int32
          description: O número da página atual.
          example: 1
    paginated_links:
      type: object
      description: Links para navegar no conjunto de resultados paginados.
      properties:
        first:
          type: string
          description: A URL para a primeira página do conjunto de resultados paginados.
          example: /{resource}?limit=20
        last:
          type: string
          description: A URL para a última página do conjunto de resultados paginados.
          example: /{resource}?page=4&limit=20
        next:
          type: string
          description: A URL para a próxima página do conjunto de resultados paginados.
          example: /{resource}?page=3&limit=20
        previous:
          type: string
          description: A URL para a página anterior do conjunto de resultados paginados.
          example: /{resource}?page=2&limit=20
    customers_paginated:
      type: object
      properties:
        items:
          type: array
          description: Um array de objetos de clientes.
          items:
            oneOf:
              - $ref: '#/components/schemas/customer_individual'
        metadata:
          $ref: '#/components/schemas/paginated_meta'
        links:
          $ref: '#/components/schemas/paginated_links'
    institutions_mexico:
      type: string
      description: >-
        Instituições disponíveis no México. Para uma lista completa de
        instituições, consulte nossa página dedicada de <a
        href="https://belvo-direct-debit.readme.io/reference/directdebit-institutions"
        target="_blank">Instituições de Pagamento</a>.
      example: mx_citi_banamex
    institutions:
      type: object
      description: Instituições
      properties:
        mx:
          type: array
          description: >-
            Instituições disponíveis no México. Para uma lista completa de
            instituições, consulte nossa página dedicada de <a
            href="https://belvo-direct-debit.readme.io/reference/directdebit-institutions"
            target="_blank">Instituições de Pagamento</a>.
          items:
            $ref: '#/components/schemas/institutions_mexico'
    accountType_mexico:
      type: string
      title: 🇲🇽 México
      enum:
        - savings
        - checking
        - debit_card
      description: |-
        O tipo de conta bancária. Pode ser:
          - `savings`
          - `checking`
          - `debit_card`
      example: savings
    bank_mexico:
      type: string
      title: 🇲🇽 México
      description: >-
        O nome do banco mexicano onde a conta está mantida.


        Para uma lista completa de instituições, consulte nossa página dedicada
        de <a
        href="https://belvo-direct-debit.readme.io/reference/directdebit-institutions"
        target="_blank">Instituições de Pagamento</a>.
      example: mx_citi_banamex
    create_payment_method:
      type: object
      required:
        - accountNumber
        - accountType
        - customerId
        - bank
      properties:
        accountNumber:
          type: string
          description: O número da conta bancária ou do cartão de débito.
          example: '445566790'
        accountType:
          $ref: '#/components/schemas/accountType_mexico'
        customerId:
          type: string
          format: uuid
          description: >-
            O identificador único criado pela Belvo usado para referenciar o
            cliente.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        bank:
          $ref: '#/components/schemas/bank_mexico'
        reference:
          type: string
          minLength: 1
          maxLength: 50
          description: Uma descrição de referência opcional para a conta bancária.
          example: SAVINGS_445566790
    paymentMethodId:
      type: object
      properties:
        paymentMethodId:
          type: string
          format: uuid
          description: >-
            O identificador único criado pela Belvo usado para referenciar o
            método de pagamento.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    type_integration_mexico:
      type: string
      title: 🇲🇽 México
      enum:
        - bank_account
      description: >-
        O tipo de conta. Para o México, esse valor é definido como
        `bank_account`.
      example: bank_account
    customer_payment_method:
      type: object
      description: Detalhes sobre o cliente associado ao método de pagamento.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: >-
            O identificador único criado pela Belvo usado para referenciar o
            cliente atual.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        firstname:
          type: string
          description: O primeiro nome do cliente.
          example: Carlos
        lastname:
          type: string
          description: O sobrenome do cliente.
          example: Vives
        email:
          type: string
          format: email
          description: O email do cliente.
          example: carlos-vives@musica.mx
        phone:
          type: string
          description: O número de telefone do cliente (incluindo o código do país).
          example: '+523001234567'
    payment_method_details:
      type: object
      description: Detalhes sobre a conta bancária associada ao método de pagamento.
      properties:
        accountNumber:
          type: string
          description: O número da conta bancária.
          example: '445566790'
        accountType:
          $ref: '#/components/schemas/accountType_mexico'
        bank:
          $ref: '#/components/schemas/bank_mexico'
    payment_method:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: >-
            O identificador único criado pela Belvo usado para referenciar o
            método de pagamento.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        createdDate:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            O timestamp ISO-8601 quando o cliente foi criado no banco de dados
            da Belvo.
          example: '2022-02-09T08:45:50.406032Z'
        lastUpdatedDate:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            O carimbo de data e hora ISO-8601 quando as informações sobre o
            cliente foram atualizadas pela última vez.
          example: '2022-02-09T08:45:50.406032Z'
        status:
          type: string
          enum:
            - pending_agreement_acceptance
            - waiting_for_activation_response
            - active
            - error
            - inactive
          description: |-
            O status do método de pagamento pode ser:

            - `pending_agreement_acceptance`<br>
              O método precisa ser aceito pelo proprietário da conta bancária. Isso pode ser feito enviando um Link de Configuração para o proprietário ou utilizando nosso recurso de API de Acordos.
              
            - `waiting_for_activation_response`<br>
              O proprietário aceitou o método de pagamento. Os arquivos de registro e cobrança foram gerados.<br>
              A instituição financeira agora precisa enviar uma resposta sobre as informações da conta bancária (OK ou Não OK).
              
            - `active`<br>
              A instituição financeira confirmou com sucesso o registro da conta bancária. O método de pagamento agora pode ser usado para solicitações de pagamento.<br>
              **Nota**: O status pode mudar para `inactive` se o proprietário cancelar ou remover o método de pagamento na instituição financeira.
              
            - `error`<br>
              A instituição financeira não conseguiu confirmar o registro da conta bancária (geralmente devido ao proprietário fornecer informações incorretas da conta bancária ou um erro na instituição financeira).
              
            - `inactive`<br>
              O método de pagamento não pode ser usado. Isso geralmente ocorre quando o proprietário cancela sua conta e a instituição financeira nos informa que o método não é mais válido.
          example: active
        type:
          $ref: '#/components/schemas/type_integration_mexico'
        customer:
          $ref: '#/components/schemas/customer_payment_method'
        details:
          $ref: '#/components/schemas/payment_method_details'
    payment_method_paginated:
      type: object
      properties:
        items:
          type: array
          description: Um array de objetos de método de pagamento do cliente.
          items:
            $ref: '#/components/schemas/payment_method'
        metadata:
          $ref: '#/components/schemas/paginated_meta'
        links:
          $ref: '#/components/schemas/paginated_links'
    payment_request:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: >-
            O identificador único criado pela Belvo usado para referenciar a
            solicitação de pagamento.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
        createdDate:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: >-
            O carimbo de data e hora ISO-8601 quando a solicitação de pagamento
            foi criada no banco de dados da Belvo.
          example: '2022-02-09T08:45:50.406032Z'
        lastUpdatedDate:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: >-
            O carimbo de data e hora ISO-8601 quando as informações sobre a
            solicitação de pagamento foram atualizadas pela última vez.
          example: '2022-02-09T08:45:50.406032Z'
        status:
          type: string
          enum:
            - initial
            - processing
            - successful
            - failed
            - canceled
          description: |-
            O status da solicitação de pagamento. Pode ser:

            - `initial`<br>
              A solicitação de pagamento foi criada.
            - `processing`<br>
              Os arquivos de cobrança foram gerados para a solicitação de pagamento. Aguardando resposta da instituição financeira.
            - `successful`<br>
              A instituição financeira confirmou a solicitação de pagamento e os fundos foram transferidos.
            - `failed`<br>
              A instituição financeira relatou um erro na solicitação de pagamento e nenhum fundo foi transferido.
            - `canceled`<br>
              A solicitação foi cancelada. Isso só é possível se a solicitação de pagamento não tiver mudado para o status `processing`.
          example: processing
        failedReason:
          type:
            - string
            - 'null'
          description: O código de falha da instituição financeira.
          example: null
        failedReasonMessage:
          type:
            - string
            - 'null'
          description: >-
            A mensagem de falha da instituição financeira, descrevendo o motivo
            da falha.
          example: null
        amount:
          type: string
          description: O valor a debitar do cliente.
          example: '100000.00'
        currency:
          type: string
          enum:
            - mxn
          description: >-
            O código de moeda de três letras ISO 4217 da transação. No momento,
            só oferecemos suporte a `mxn`.
          example: mxn
        customer:
          type: string
          format: uuid
          description: >-
            O identificador único criado pela Belvo usado para referenciar o
            cliente.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        customerName:
          type: string
          description: O nome do cliente.
          example: Carlos Vives
        reference:
          type: string
          minLength: 1
          maxLength: 160
          description: Uma referência para a solicitação de pagamento.
          example: Monthly gym subscription
        paymentMethod:
          type: object
          properties:
            type:
              $ref: '#/components/schemas/type_integration_mexico'
            details:
              $ref: '#/components/schemas/payment_method_details'
        loanInformation:
          type: object
          description: >-
            (Metadata opcional) Metadados sobre o empréstimo associado à
            solicitação de pagamento.
          properties:
            reference:
              type: string
              maxLength: 50
              description: >-
                Sua referência para o empréstimo associado à solicitação de
                pagamento.
              example: Camera Purchase 1432
            disbursementDate:
              type: string
              format: date
              description: >-
                A data em que o empréstimo foi desembolsado, no formato
                YYYY-MM-DD.
              example: '2025-01-01'
            installmentNumber:
              type: integer
              description: O número da parcela que está sendo paga.
              example: 1
            installmentAmount:
              type: number
              format: float
              pattern: ^\d{1,15}\.\d{2,4}$
              description: O valor da parcela sendo paga.
              example: 100.02
            installmentDueDate:
              type: string
              format: date
              description: >-
                A data de vencimento da parcela que está sendo paga, no formato
                YYYY-MM-DD.
              example: '2025-03-01'
            totalAmount:
              type: number
              format: float
              pattern: ^\d{1,15}\.\d{2,4}$
              description: O valor total do empréstimo.
              example: 12000.24
            totalInstallments:
              type: integer
              description: O número total de parcelas para o empréstimo.
              example: 12
    payment_request_paginated:
      type: object
      properties:
        items:
          type: array
          description: Um array de objetos de solicitação de pagamento.
          items:
            $ref: '#/components/schemas/payment_request'
        metadata:
          $ref: '#/components/schemas/paginated_meta'
        links:
          $ref: '#/components/schemas/paginated_links'
    create_payment_request_existing:
      type: object
      title: Método de pagamento existente
      description: >-
        O corpo da solicitação para criar uma solicitação de pagamento para um
        método de pagamento existente.
      required:
        - amount
        - currency
        - reference
        - paymentMethodId
      properties:
        amount:
          type: number
          format: float
          description: O valor a debitar do cliente.
          example: 1000
        currency:
          type: string
          enum:
            - mxn
          description: >-
            O código de moeda de três letras ISO 4217 da transação. No momento,
            só oferecemos suporte a `mxn`.
          example: mxn
        reference:
          type: string
          minLength: 1
          maxLength: 50
          description: Sua referência interna para a solicitação de pagamento.
          example: J-789029-PAY-3X
        paymentMethodId:
          type: string
          format: uuid
          description: >-
            O identificador único criado pela Belvo usado para referenciar o
            método de pagamento.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
        loanInformation:
          type: object
          description: >-
            (Metadata opcional) Metadados sobre o empréstimo associado à
            solicitação de pagamento.
          properties:
            reference:
              type: string
              maxLength: 50
              description: >-
                Sua referência para o empréstimo associado à solicitação de
                pagamento.
              example: Camera Purchase 1432
            disbursementDate:
              type: string
              format: date
              description: >-
                A data em que o empréstimo foi desembolsado, no formato
                YYYY-MM-DD.
              example: '2025-01-01'
            installmentNumber:
              type: integer
              description: O número da parcela que está sendo paga.
              example: 1
            installmentAmount:
              type: number
              format: float
              pattern: ^\d{1,15}\.\d{2,4}$
              description: O valor da parcela sendo paga.
              example: 100.02
            installmentDueDate:
              type: string
              format: date
              description: >-
                A data de vencimento da parcela que está sendo paga, no formato
                YYYY-MM-DD.
              example: '2025-03-01'
            totalAmount:
              type: number
              format: float
              pattern: ^\d{1,15}\.\d{2,4}$
              description: O valor total do empréstimo.
              example: 12000.24
            totalInstallments:
              type: integer
              description: O número total de parcelas para o empréstimo.
              example: 12
    paymentRequestId:
      type: object
      properties:
        paymentRequestId:
          type: string
          format: uuid
          description: >-
            O identificador único criado pela Belvo usado para referenciar a
            solicitação de pagamento.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    movement:
      type: object
      description: Um movimento individual na conta do cliente.
      properties:
        id:
          type: string
          format: uuid
          description: >-
            O identificador único criado pela Belvo usado para referenciar o
            movimento.
          example: 38848ec1-79bb-4827-87b1-819f186ad273
        createdDate:
          type: string
          format: date-time
          description: >-
            O carimbo de data e hora ISO-8601 quando o movimento foi criado no
            banco de dados da Belvo.
          example: '2025-05-14T16:20:00Z'
        lastUpdatedDate:
          type: string
          format: date-time
          description: >-
            O carimbo de data e hora ISO-8601 quando as informações sobre o
            movimento foram atualizadas pela última vez.
          example: '2025-05-14T16:25:00Z'
        chargebackDate:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            O timestamp ISO-8601 de quando o estorno foi iniciado pela
            instituição bancária (aplicável apenas se o movimento foi causado
            por um estorno (`reason` = `payments_service_chargeback`)).
          example: null
        type:
          type: string
          enum:
            - credit
            - debit
          description: |-
            O tipo de movimento. Pode ser:
              - `credit` (dinheiro depositado na sua conta)
              - `debit` (dinheiro retirado da sua conta)
          example: credit
        reason:
          type: string
          enum:
            - withdrawal
            - payments_service_charge
            - payments_service_fee
            - payments_service_fee_tax
            - payments_service_chargeback
            - penny_validation_fee
            - penny_validation_fee_tax
            - adjustment
          description: |-
            A razão para o movimento. Pode ser:

              - `withdrawal`: O saldo foi transferido para a conta do comerciante.
              - `payments_service_charge`: Uma cobrança bem-sucedida ocorreu.
              - `payments_service_fee`: A taxa da Belvo para uma cobrança bem-sucedida ou falha.
              - `payments_service_fee_tax`: O imposto sobre a `payments_service_fee`.
              - `payments_service_chargeback`: Um estorno ocorreu.
              - `penny_validation_fee`: A taxa da Belvo para uma validação de centavos.
              - `penny_validation_fee_tax`: O imposto sobre a `penny_validation_fee`.
              - `adjustment`: Usado no caso de qualquer outro movimento necessário para ajustar o saldo do comerciante.
          example: payments_service_fee
        amount:
          type: number
          format: float
          description: O valor do movimento.
          example: 125.5
        currency:
          type: string
          minLength: 3
          maxLength: 3
          pattern: ^[A-Z]{3}$
          description: O código de moeda de três letras (ISO-4217).
          example: MXN
        paymentRequest:
          type: string
          format: uuid
          description: O ID da solicitação de pagamento associada.
          example: 136771f0-13d7-4725-ae0b-e25e9055716d
        paymentRequestReference:
          type:
            - string
            - 'null'
          description: Uma referência para a solicitação de pagamento.
          example: INV-2025-001
        paymentRequestDisplayReference:
          type:
            - string
            - 'null'
          description: >-
            Uma descrição de referência exibida no extrato bancário do seu
            cliente.
          example: Payment to ACME Corp
        customerName:
          type: string
          description: O nome do cliente associado ao movimento.
          example: Juan Pérez
        customerDocumentType:
          type: string
          enum:
            - mx_rfc
            - mx_curp
          description: >-
            O tipo de documento do cliente. Para 🇲🇽 México, pode ser um dos
            seguintes:
              - `mx_rfc`: Número de Identificação Fiscal (Registro Federal de Contribuyentes)
              - `mx_curp`: Código Único de Registro de População (Clave Única de Registro de Población)
          example: mx_rfc
        customerDocumentNumber:
          type: string
          description: O número do documento do cliente.
          example: HEGJ850506SX1
        paymentMethodType:
          type: string
          enum:
            - bank_account
          description: >-
            O tipo de método de pagamento. Para o México, esse valor é definido
            como `bank_account`.
          example: bank_account
        accountNumber:
          type: string
          description: O número da conta do seu cliente.
          example: 12345678901234568
        withdrawalId:
          type:
            - string
            - 'null'
          description: ID Interno da Belvo para movimentos onde o `reason` é `withdrawal`.
          example: 9e637645-efe8-4fb7-a442-fa2eeb5ad606
        withdrawalCreatedDate:
          type:
            - string
            - 'null'
          format: date-time
          description: O timestamp ISO-8601 para movimentos onde o `reason` é `withdrawal`.
          example: '2025-05-10T14:30:00Z'
        withdrawalExtra:
          type:
            - object
            - 'null'
          description: >-
            Um objeto personalizável contendo pares chave-valor adicionais que
            você solicitou que a Belvo incluísse para movimentos onde o `reason`
            é `withdrawal`.
          example:
            reference_id: ABC123
            withdrawal_method: bank_transfer
    movement_paginated:
      type: object
      properties:
        items:
          type: array
          description: Um array de objetos de movimento.
          items:
            $ref: '#/components/schemas/movement'
        metadata:
          $ref: '#/components/schemas/paginated_meta'
        links:
          $ref: '#/components/schemas/paginated_links'
    consent:
      type: object
      required:
        - consentId
        - status
        - paymentMethodId
        - isBankNotified
      properties:
        consentId:
          type: string
          format: uuid
          readOnly: true
          description: >-
            O identificador único criado pela Belvo usado para referenciar o
            consentimento.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
        status:
          type: string
          enum:
            - awaiting_information
            - submitted
            - confirmed
            - incomplete_information
            - rejected
            - received_chargeback
          description: >-
            O status do consentimento. Pode ser um dos seguintes:


            **Inicial**:

            - `awaiting_information`: O consentimento foi criado e agora os
            arquivos acompanhantes devem ser enviados.


            **Após o envio dos arquivos**:

            - `submitted`: Todos os documentos necessários foram enviados e o
            consentimento está pendente de confirmação.

            - `incomplete_information`: Um ou mais arquivos estão faltando ou
            são inválidos.


            **Estados finais**:

            - `confirmed`: Os arquivos associados foram revisados e aceitos. O
            consentimento agora está ativo e você pode fazer solicitações de
            pagamento.

            - `rejected`: Os documentos enviados foram rejeitados e o
            consentimento não foi concedido.

            - `received_chargeback`: O cliente recebeu um chargeback após o
            consentimento ter sido `confirmed`.
        paymentMethodId:
          type: string
          format: uuid
          readOnly: true
          description: >-
            O identificador único criado pela Belvo usado para referenciar o
            método de pagamento.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
        isBankNotified:
          type: boolean
          readOnly: true
          description: >-
            Indica se o banco foi notificado sobre o Consentimento. Isso é
            definido como `true` no caso de um chargeback ser recebido e a
            evidência do Consentimento ter sido enviada para o banco.
          example: false
    consent_id_file:
      type: object
      required:
        - type
        - consentFileId
        - consentId
      properties:
        type:
          type: string
          enum:
            - id_front
            - id_back
            - selfie
            - contract
          description: |-
            O tipo de arquivo de Consentimento. Pode ser um dos seguintes:
              - `id_front`
              - `id_back`
              - `selfie`
              - `contract`
          example: id_front
        consentFileId:
          type: string
          format: uuid
          readOnly: true
          description: >-
            O identificador único criado pela Belvo usado para referenciar o
            arquivo de Consentimento.
          example: 8c56b4e7-d025-4b1a-a303-dd472b24f431
        consentId:
          type: string
          format: uuid
          readOnly: true
          description: >-
            O identificador único criado pela Belvo usado para referenciar o
            Consent.
          example: 0494baff-3bbb-43c7-bb58-67ac6cba3e54
  parameters:
    page:
      name: page
      required: false
      in: query
      description: Um número de página dentro do conjunto de resultados paginados.
      schema:
        example: 1
        format: int32
        type: integer
    limit:
      name: limit
      required: false
      in: query
      description: >-
        Indica quantos resultados retornar por página. Por padrão, retornamos 20
        resultados por página.


        ℹ️ O número mínimo de resultados retornados por página é 1 e o máximo é
        100. Se você inserir um valor maior que 100, nossa API usará o valor
        máximo (100) por padrão.
      schema:
        type: integer
        format: int32
        default: 20
        minimum: 1
        maximum: 100
        example: 15
    search_customer:
      name: search
      required: false
      in: query
      description: >-
        Retorne resultados que correspondam ao `email`, `firstname`, `lastname`
        ou `documentNumber` que você pesquisou.


        **Nota:**


        Este filtro suporta consultas de pesquisa completas e parciais.


        Por exemplo, pesquisar por `car` pode corresponder aos seguintes
        valores:

          - `carlos.vives@musicamexico.mx` (`email`)
          - `Carlos` (`firstname`)
          - `Cartregena` (`lastname`)
          - `789-CAR-789456789` (`documentNumber`)
      schema:
        type: string
        example: trai
    customerId:
      name: customerId
      required: true
      in: path
      description: >-
        O identificador único criado pela Belvo usado para referenciar o
        cliente.
      schema:
        type: string
        format: uuid
        example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    search__general:
      name: search
      required: false
      in: query
      description: >-
        Retorne resultados que correspondam à `reference` que você pesquisou.


        **Nota:**

        Este filtro suporta consultas de pesquisa completas e parciais. Por
        exemplo, pesquisar por `trai` pode corresponder aos seguintes valores
        (extraídos do campo `reference`):


        - `Awesome training sneakers`

        - `Training equipment`
      schema:
        type: string
        example: trai
    customer_id:
      name: customer_id
      required: false
      in: query
      description: >-
        O identificador único criado pela Belvo usado para referenciar o
        cliente.
      schema:
        type: string
        format: uuid
        example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    type:
      name: type
      required: false
      in: query
      description: |-
        O tipo de conta. Pode ser:

          - `bank_account`
            Usado para a maioria das contas bancárias.
      schema:
        type: string
        enum:
          - bank_account
        example: bank_account
    paymentMethodId:
      name: paymentMethodId
      required: true
      in: path
      description: >-
        O identificador único criado pela Belvo usado para referenciar o método
        de pagamento.
      schema:
        type: string
        format: uuid
        example: d5f2e1a8-f449-4338-bd6a-df62b3fbf0b3
    order:
      name: order
      required: false
      in: query
      description: >-
        Retorne os resultados em ordem ascendente (do mais antigo para o mais
        recente) ou descendente (do mais recente para o mais antigo), de acordo
        com o `createdDate`.


        Pode ser:
          - `asc` para ordem ascendente
          - `desc` para ordem descendente
      schema:
        enum:
          - asc
          - desc
        example: asc
        type: string
    start_date:
      name: start_date
      required: false
      in: query
      description: >-
        Retorne itens com um `createdDate` maior ou igual à data especificada. A
        data deve estar no formato `YYYY-MM-DD`.
      schema:
        type: string
        format: date
        pattern: ^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$
        example: '2024-01-01'
    end_date:
      name: end_date
      required: false
      in: query
      description: >-
        Retorne itens com um `createdDate` menor ou igual à data especificada. A
        data deve estar no formato `YYYY-MM-DD`.
      schema:
        type: string
        format: date
        pattern: ^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$
        example: '2024-01-30'
    idempotency_key:
      name: Idempotency-Key
      required: false
      in: header
      description: >-
        (Opcional, mas altamente recomendado.) Um identificador único para esta
        solicitação para suportar idempotência. Use um UUID ou identificador
        similar. Para mais informações, consulte nosso artigo dedicado sobre <a
        href="https://developers.belvo.com/docs/direct-debit-idempotency-and-whitelisting"
        target="_blank">Idempotência</a>.
      schema:
        type: string
    paymentRequestId:
      name: paymentRequestId
      required: true
      in: path
      description: >-
        O identificador único criado pela Belvo usado para referenciar a
        solicitação de pagamento.
      schema:
        type: string
        format: uuid
        example: 2e66d035-c78f-435c-a21d-b86d3e7b351d
    from_created_date:
      name: from_created_date
      in: query
      description: Filtre movimentos criados nesta data ou após, no formato `YYYY-MM-DD`.
      required: false
      schema:
        type: string
        format: date
    until_created_date:
      name: until_created_date
      in: query
      description: Filtrar movimentos criados nesta data ou antes, no formato `YYYY-MM-DD`.
      required: false
      schema:
        type: string
        format: date
    type_movement:
      name: type
      in: query
      description: Filtrar movimentos por um destes tipos (`credit` ou `debit`).
      required: false
      schema:
        type: string
        enum:
          - credit
          - debit
    withdrawal_id:
      name: withdrawal_id
      in: query
      description: Filtrar movimentos por este ID de retirada.
      required: false
      schema:
        type: string
    reason:
      name: reason
      in: query
      description: |-
        Filtre movimentos por um ou mais dos seguintes motivos:
        - withdrawal
        - payments_service_charge
        - payments_service_fee
        - payments_service_fee_tax
        - payments_service_chargeback
        - penny_validation_fee
        - penny_validation_fee_tax
        - adjustment
      required: false
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
            - withdrawal
            - payments_service_charge
            - payments_service_fee
            - payments_service_fee_tax
            - payments_service_chargeback
            - penny_validation_fee
            - penny_validation_fee_tax
            - adjustment
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true
