openapi: 3.1.0
info:
  title: API de Débito Directo de Belvo
  version: 1.0.0
  description: >-
    Nuestra infraestructura de pagos tiene como objetivo facilitar, acelerar y
    modular el movimiento de dinero entre empresas y personas.
  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: Instituciones de Débito Directo
  - name: Customers (Direct Debit Mexico)
    description: >-
      Un Cliente es el usuario final, ya sea un individuo o un negocio, que
      posee la cuenta bancaria involucrada en una operación de débito o pago.
      Belvo Direct Debit almacena la información esencial de este Cliente para
      simplificar y reutilizarla en múltiples métodos de pago y objetivos de
      pago.
  - name: Payment Methods (Direct Debit Mexico)
    description: Métodos de Pago
  - name: Payment Requests (Direct Debit Mexico)
    description: Solicitudes de Pago
  - name: Movements (Direct Debit Mexico)
    description: >-
      Los Movimientos de Cuenta son las transacciones que ocurren dentro de tu
      cuenta bancaria.
  - name: Payment Consents (Direct Debit Mexico)
    description: >-
      Un Consentimiento en Débito Directo es una prueba de su cliente de que ha
      confirmado que se le debitarán fondos de su cuenta (Método de Pago). Esta
      prueba se compone de fotos de su identificación, una selfie y un contrato
      firmado.
paths:
  /customers:
    post:
      summary: Crear un cliente
      description: Crear un nuevo cliente de Débito Directo
      operationId: CreateDirectDebitCustomer
      security:
        - ApiKeyAuth: []
        - ApiKeySecret: []
      tags:
        - Customers (Direct Debit Mexico)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/create_customer_individual'
      responses:
        '201':
          description: Creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerId'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /customers/:
    get:
      summary: Listar todos los clientes
      description: Enumere todos los clientes de Débito Directo asociados con su cuenta.
      operationId: ListDirectDebitCustomers
      security:
        - ApiKeyAuth: []
        - ApiKeySecret: []
      tags:
        - Customers (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/search_customer'
      responses:
        '200':
          description: De acuerdo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customers_paginated'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /customers/{customerId}:
    post:
      summary: Actualizar un cliente
      description: Actualizar un cliente de débito directo existente
      operationId: UpdateDirectDebitCustomer
      security:
        - ApiKeyAuth: []
        - ApiKeySecret: []
      tags:
        - Customers (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/customerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/create_customer_individual'
      responses:
        '201':
          description: Creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerId'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
    get:
      summary: Obtener los detalles de un cliente
      description: Obtener los detalles sobre un cliente específico de débito directo.
      operationId: DetailDirectDebitCustomer
      security:
        - ApiKeyAuth: []
        - ApiKeySecret: []
      tags:
        - Customers (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/customerId'
      responses:
        '200':
          description: De acuerdo
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/customer_individual'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /institutions:
    get:
      summary: Enumera todas las instituciones.
      description: Enumera todas las instituciones disponibles.
      operationId: ListDirectDebitInstitutions
      security:
        - ApiKeyAuth: []
        - ApiKeySecret: []
      tags:
        - Institutions (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: De acuerdo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/institutions'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /payment_methods/bank_accounts:
    post:
      summary: Crear un método de pago
      description: Crear un nuevo método de pago para un cliente
      operationId: CreateDirectDebitPaymentMethod
      security:
        - ApiKeyAuth: []
        - ApiKeySecret: []
      tags:
        - Payment Methods (Direct Debit Mexico)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_payment_method'
      responses:
        '201':
          description: Creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paymentMethodId'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /payment_methods:
    get:
      summary: Enumera todos los métodos de pago.
      description: Enumere todos los métodos de pago asociados con su cuenta.
      operationId: ListDirectDebitPaymentMethods
      security:
        - ApiKeyAuth: []
        - ApiKeySecret: []
      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: De acuerdo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method_paginated'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /payment_methods/{paymentMethodId}:
    get:
      summary: Obtener los detalles de un método de pago
      description: Obtén los detalles sobre un método de pago específico.
      operationId: DetailDirectDebitPaymentMethod
      security:
        - ApiKeyAuth: []
        - ApiKeySecret: []
      tags:
        - Payment Methods (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/paymentMethodId'
      responses:
        '200':
          description: De acuerdo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /payment_methods/{paymentMethodId}/deactivate:
    post:
      summary: Desactivar un método de pago
      description: >-
        Desactivar un método de pago específico.


        > 📘 Información

        >

        > Solo puedes desactivar un método de pago cuando el `status` está en el
        estado `active` y no hay solicitudes de pago pendientes
        (`paymentRequest.status` = `processing`).
      operationId: DeactivateDirectDebitPaymentMethod
      security:
        - ApiKeyAuth: []
        - ApiKeySecret: []
      tags:
        - Payment Methods (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/paymentMethodId'
      responses:
        '201':
          description: Creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /payment_requests:
    post:
      summary: Crear una solicitud de pago
      description: |-
        Crea una nueva solicitud de pago para un método de pago existente.

        > 📘 Claves de Idempotencia
        >
        > Este método admite claves de idempotencia.
      operationId: CreateDirectDebitPaymentRequest
      security:
        - ApiKeyAuth: []
        - ApiKeySecret: []
      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: Solicitud de Pago Creada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paymentRequestId'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
    get:
      summary: Enumere todas las solicitudes de pago.
      description: Enumere todas las solicitudes de pago asociadas con su cuenta.
      operationId: ListDirectDebitPaymentRequests
      security:
        - ApiKeyAuth: []
        - ApiKeySecret: []
      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: De acuerdo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_request_paginated'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /payment_requests/{paymentRequestId}:
    get:
      summary: Obtener los detalles de una solicitud de pago
      description: Obtén los detalles sobre una solicitud de pago específica.
      operationId: DetailDirectDebitPaymentRequest
      security:
        - ApiKeyAuth: []
        - ApiKeySecret: []
      tags:
        - Payment Requests (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/paymentRequestId'
      responses:
        '200':
          description: De acuerdo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_request'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /payment_requests/{paymentRequestId}/cancel:
    post:
      summary: Cancelar una solicitud de pago
      description: >-
        Cancelar una solicitud de pago.


        > 📘 Información

        >

        > Solo puedes cancelar una solicitud de pago cuando el `status` está en
        el estado `initial`.
      operationId: CancelDirectDebitPaymentRequest
      security:
        - ApiKeyAuth: []
        - ApiKeySecret: []
      tags:
        - Payment Requests (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/paymentRequestId'
      responses:
        '201':
          description: Creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_request'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /account_movements:
    get:
      summary: Obtén los movimientos de tu cuenta
      description: Obtén un estado de los movimientos que han ocurrido dentro de tu cuenta.
      operationId: ListDirectDebitAccountMovements
      security:
        - ApiKeyAuth: []
        - ApiKeySecret: []
      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: De acuerdo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/movement_paginated'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
  /consents:
    post:
      summary: Crear un Consentimiento
      description: >-
        Cree el Consentimiento inicial para un Método de Pago. Una vez que cree
        un Consentimiento, puede cargar documentos de respaldo que sirvan como
        consentimiento de su cliente para debitar su cuenta bancaria utilizando
        el 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: >-
                    El identificador único creado por Belvo utilizado para
                    referenciar el método de pago para el cual deseas cargar
                    documentos de consentimiento.
                  example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
      responses:
        '201':
          description: Consentimiento Creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/consent'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
    get:
      summary: Lista todos los Consents
      description: >-
        Enumere todos los Consentimientos que ha creado para sus Métodos de
        Pago.
      operationId: ListAllConsents
      tags:
        - Payment Consents (Direct Debit Mexico)
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Lista de Consentimientos
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                  - metadata
                  - links
                properties:
                  items:
                    type: array
                    description: Un arreglo de objetos de consentimiento.
                    items:
                      $ref: '#/components/schemas/consent'
                  metadata:
                    $ref: '#/components/schemas/paginated_meta'
                  links:
                    $ref: '#/components/schemas/paginated_links'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /consents/{consentId}:
    get:
      summary: Obtener los Detalles de un Consentimiento
      operationId: GetConsentDetails
      description: Obtén los detalles de un consentimiento específico.
      tags:
        - Payment Consents (Direct Debit Mexico)
      parameters:
        - name: consentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: El ID del consentimiento para el que deseas obtener detalles.
      responses:
        '200':
          description: Detalles del Consentimiento
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/consent'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
  /consents/{consentId}/files:
    post:
      summary: Subir archivos de consentimiento
      description: >-
        Sube archivos que sirvan como consentimiento de tu cliente para debitar
        su cuenta bancaria. Debes subir todos los archivos requeridos para un
        Consentimiento (escaneos del anverso y reverso del documento de
        identidad, una selfie del usuario sosteniendo el documento de identidad
        y un contrato firmado). Cada archivo no puede ser mayor de 20MB.
      operationId: UploadConsentFiles
      tags:
        - Payment Consents (Direct Debit Mexico)
      parameters:
        - name: consentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: El ID del Consentimiento para el que deseas subir archivos.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - id_front
                - id_back
                - selfie
                - contract
              description: >-
                Los archivos para cargar para el Consentimiento. Cada archivo no
                puede ser mayor de 20MB.
              properties:
                id_front:
                  type: string
                  format: binary
                  description: >-
                    La parte frontal escaneada/foto de la identificación del
                    usuario.
                id_back:
                  type: string
                  format: binary
                  description: >-
                    La parte trasera escaneada/foto de la identificación del
                    usuario.
                selfie:
                  type: string
                  format: binary
                  description: Una selfie del usuario sosteniendo su identificación.
                contract:
                  type: string
                  format: binary
                  description: Un contrato firmado por el usuario autorizando el débito.
      responses:
        '201':
          description: Archivos de Consentimiento Cargados
          content:
            application/json:
              schema:
                type: array
                description: >-
                  Un array de objetos de archivo de Consent que han sido
                  subidos.
                items:
                  $ref: '#/components/schemas/consent_id_file'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404_not_found_error'
    get:
      summary: Obtener los archivos de un Consentimiento
      description: Enumere todos los archivos que se han subido para un Consent específico.
      operationId: ListConsentFiles
      tags:
        - Payment Consents (Direct Debit Mexico)
      parameters:
        - name: consentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: El ID del Consentimiento para el que deseas obtener archivos.
      responses:
        '200':
          description: Lista de archivos
          content:
            application/json:
              schema:
                type: array
                description: Una matriz de objetos de archivo de Consent.
                items:
                  $ref: '#/components/schemas/consent_id_file'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_bad_request_error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_unauthorized_error'
        '404':
          description: No 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: Individuo
      enum:
        - mx_rfc
        - mx_curp
      description: |-
        El tipo de documento del individuo.

        Para 🇲🇽 México, puede ser uno de los siguientes:
          - `mx_rfc`: Número de Identificación Fiscal (*Registro Federal de Contribuyentes*)
          - `mx_curp`: Clave Única de Registro de Población (*Clave Única de Registro de Población*)
      example: mx_rfc
    create_customer_individual:
      type: object
      title: Individuo
      description: Cuerpo de la solicitud para crear un cliente de débito directo.
      required:
        - firstname
        - lastname
        - email
        - documentType
        - documentNumber
      properties:
        firstname:
          type: string
          minLength: 1
          maxLength: 50
          description: El primer nombre del cliente.
          example: Carlos
        lastname:
          type: string
          minLength: 1
          maxLength: 50
          description: El apellido del cliente.
          example: Vives
        email:
          type: string
          format: email
          description: El correo electrónico del cliente.
          example: carlos-vives@musica.mx
        documentType:
          $ref: '#/components/schemas/documentType_individual'
        documentNumber:
          type: string
          description: >-
            El número de documento del cliente.  

            Para México, este debe tener 18 caracteres.


            > **Nota**: Si el `documentNumber` no coincide con la longitud y el
            formato de caracteres esperados para un `documentType` dado,
            devolvemos un error `400 input_validation`.
          example: '123456789'
        phone:
          type: string
          description: El número de teléfono del cliente (incluido el código de país).
          example: '+523001234567'
    customerId:
      type: object
      properties:
        customerId:
          type: string
          format: uuid
          readOnly: true
          description: >-
            El identificador único creado por Belvo utilizado para referenciar
            al cliente.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    400_bad_request_error:
      type: object
      title: Solicitud incorrecta
      description: >-
        Este error ocurre cuando los parámetros proporcionados no coinciden con
        los campos esperados o el elemento que estás intentando crear ya está en
        nuestra base de datos.
      properties:
        statusCode:
          type: integer
          description: El código de estado HTTP para este error.
          example: 400
        error:
          type: string
          description: La descripción del código de estado HTTP para este error.
          example: Bad Request
        message:
          oneOf:
            - type: string
              title: Cadena Única
            - type: array
              title: Matriz de cadenas
              items:
                type: string
          description: >-
            Una breve descripción del error, indicando qué está mal con la
            solicitud.

            > **Nota**: Devolvemos una cadena o un arreglo de cadenas,
            dependiendo del/los error(es) de validación.


            La descripción puede ser (entre otras):

              - `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: No autorizado
      description: >-
        Este error ocurre cuando intentas realizar una llamada API utilizando
        credenciales incorrectas de la API de Belvo (ya sea tu clave secreta o
        contraseña secreta, o ambas, son incorrectas).
      properties:
        statusCode:
          type: integer
          description: El código de estado HTTP para este error.
          example: 401
        error:
          type: string
          description: La descripción del código de estado HTTP para este error.
          example: Unauthorized
        message:
          type: string
          description: >-
            Una breve descripción del error, indicando qué está mal con la
            solicitud. En el caso de un error 401 Unauthorized, el mensaje es:

              - `Unauthorized credentials`
          example: Unauthorized credentials
    404_not_found_error:
      type: object
      title: No encontrado
      properties:
        statusCode:
          type: integer
          description: El código de estado HTTP para este error.
          example: 404
        error:
          type: string
          description: La descripción del código de estado HTTP para este error.
          example: Not Found
        message:
          type: string
          description: >-
            Una breve descripción del error, indicando qué está mal con la
            solicitud. La descripción puede ser (entre otras):

              - `Payout Target not found`
              - `Payment method not found`
              - `Customer not found`
          example: Payout Target not found
    customer_individual:
      type: object
      title: Individuo
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: >-
            El identificador único creado por Belvo utilizado para referenciar
            al cliente.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        createdDate:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: >-
            La marca de tiempo ISO-8601 cuando el cliente fue creado en la base
            de datos de Belvo.
          example: '2022-02-09T08:45:50.406032Z'
        lastUpdatedDate:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: >-
            La marca de tiempo ISO-8601 cuando se actualizó por última vez la
            información sobre el cliente.
          example: '2022-02-09T08:45:50.406032Z'
        firstname:
          type: string
          minLength: 1
          maxLength: 50
          description: El primer nombre del cliente.
          example: Carlos
        lastname:
          type: string
          minLength: 1
          maxLength: 50
          description: El apellido del cliente.
          example: Vives
        email:
          type: string
          format: email
          description: El correo electrónico del cliente.
          example: carlos-vives@musica.mx
        phone:
          type: string
          description: El número de teléfono del cliente (incluido el código de país).
          example: '+523001234567'
        country:
          type: string
          pattern: ^[a-z]{3}$
          description: El código de país de tres letras ISO 3166-1 alpha-3 del cliente.
          example: mex
        documentType:
          $ref: '#/components/schemas/documentType_individual'
        documentNumber:
          type: string
          description: El número de documento del cliente.
          example: '123456789'
    paginated_meta:
      type: object
      description: Metadatos adicionales sobre el conjunto de resultados paginados.
      properties:
        totalItems:
          type: integer
          format: int32
          description: El número total de elementos en el conjunto de resultados paginados.
          example: 100
        itemCount:
          type: integer
          format: int32
          description: El número de elementos en la página actual.
          example: 10
        itemsPerPage:
          type: integer
          format: int32
          description: El número de elementos solicitados por página.
          example: 10
        totalPages:
          type: integer
          format: int32
          description: El número total de páginas en el conjunto de resultados paginados.
          example: 10
        currentPage:
          type: integer
          format: int32
          description: El número de página actual.
          example: 1
    paginated_links:
      type: object
      description: Enlaces para navegar por el conjunto de resultados paginados.
      properties:
        first:
          type: string
          description: La URL a la primera página del conjunto de resultados paginados.
          example: /{resource}?limit=20
        last:
          type: string
          description: La URL a la última página del conjunto de resultados paginados.
          example: /{resource}?page=4&limit=20
        next:
          type: string
          description: La URL a la siguiente página del conjunto de resultados paginados.
          example: /{resource}?page=3&limit=20
        previous:
          type: string
          description: La URL a la página anterior del conjunto de resultados paginados.
          example: /{resource}?page=2&limit=20
    customers_paginated:
      type: object
      properties:
        items:
          type: array
          description: Un array de objetos de cliente.
          items:
            oneOf:
              - $ref: '#/components/schemas/customer_individual'
        metadata:
          $ref: '#/components/schemas/paginated_meta'
        links:
          $ref: '#/components/schemas/paginated_links'
    institutions_mexico:
      type: string
      description: >-
        Instituciones disponibles en México. Para ver una lista completa de
        instituciones, por favor visita nuestra página dedicada a <a
        href="https://belvo-direct-debit.readme.io/reference/directdebit-institutions"
        target="_blank">Instituciones de Pago</a>.
      example: mx_citi_banamex
    institutions:
      type: object
      description: Instituciones
      properties:
        mx:
          type: array
          description: >-
            Instituciones disponibles en México. Para obtener una lista completa
            de instituciones, consulte nuestra página dedicada a <a
            href="https://belvo-direct-debit.readme.io/reference/directdebit-institutions"
            target="_blank">Instituciones de Pago</a>.
          items:
            $ref: '#/components/schemas/institutions_mexico'
    accountType_mexico:
      type: string
      title: 🇲🇽 México
      enum:
        - savings
        - checking
        - debit_card
      description: |-
        El tipo de cuenta bancaria. Puede ser:
          - `savings`
          - `checking`
          - `debit_card`
      example: savings
    bank_mexico:
      type: string
      title: 🇲🇽 México
      description: >-
        El nombre del banco mexicano donde se mantiene la cuenta.


        Para obtener una lista completa de instituciones, consulte nuestra
        página dedicada de <a
        href="https://belvo-direct-debit.readme.io/reference/directdebit-institutions"
        target="_blank">Instituciones de Pago</a>.
      example: mx_citi_banamex
    create_payment_method:
      type: object
      required:
        - accountNumber
        - accountType
        - customerId
        - bank
      properties:
        accountNumber:
          type: string
          description: El número de cuenta bancaria o de tarjeta de débito.
          example: '445566790'
        accountType:
          $ref: '#/components/schemas/accountType_mexico'
        customerId:
          type: string
          format: uuid
          description: >-
            El identificador único creado por Belvo utilizado para referenciar
            al cliente.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        bank:
          $ref: '#/components/schemas/bank_mexico'
        reference:
          type: string
          minLength: 1
          maxLength: 50
          description: Una descripción de referencia opcional para la cuenta bancaria.
          example: SAVINGS_445566790
    paymentMethodId:
      type: object
      properties:
        paymentMethodId:
          type: string
          format: uuid
          description: >-
            El identificador único creado por Belvo utilizado para referenciar
            el método de pago.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    type_integration_mexico:
      type: string
      title: 🇲🇽 México
      enum:
        - bank_account
      description: >-
        El tipo de cuenta. Para México, este valor se establece en
        `bank_account`.
      example: bank_account
    customer_payment_method:
      type: object
      description: Detalles relacionados con el cliente asociado con el método de pago.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: >-
            El identificador único creado por Belvo utilizado para referenciar
            al cliente actual.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        firstname:
          type: string
          description: El primer nombre del cliente.
          example: Carlos
        lastname:
          type: string
          description: El apellido del cliente.
          example: Vives
        email:
          type: string
          format: email
          description: El correo electrónico del cliente.
          example: carlos-vives@musica.mx
        phone:
          type: string
          description: El número de teléfono del cliente (incluido el código de país).
          example: '+523001234567'
    payment_method_details:
      type: object
      description: >-
        Detalles relacionados con la cuenta bancaria asociada con el método de
        pago.
      properties:
        accountNumber:
          type: string
          description: El número de cuenta bancaria.
          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: >-
            El identificador único creado por Belvo utilizado para referenciar
            el método de pago.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        createdDate:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            La marca de tiempo ISO-8601 cuando el cliente fue creado en la base
            de datos de Belvo.
          example: '2022-02-09T08:45:50.406032Z'
        lastUpdatedDate:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            La marca de tiempo ISO-8601 cuando se actualizó por última vez la
            información sobre el cliente.
          example: '2022-02-09T08:45:50.406032Z'
        status:
          type: string
          enum:
            - pending_agreement_acceptance
            - waiting_for_activation_response
            - active
            - error
            - inactive
          description: |-
            El estado del método de pago. Puede ser:

            - `pending_agreement_acceptance`<br>
              El método necesita ser aceptado por el propietario de la cuenta bancaria. Esto se puede hacer enviando un Enlace de Configuración al propietario o utilizando nuestro recurso API de Acuerdos.
            - `waiting_for_activation_response`<br>
              El propietario ha aceptado el método de pago. Los archivos de registro y de cargo han sido generados.<br>
              La institución financiera ahora necesita enviar una respuesta sobre la información de la cuenta bancaria (OK o No OK).
            - `active`<br>
              La institución financiera ha confirmado exitosamente el registro de la cuenta bancaria. El método de pago ahora puede ser utilizado para solicitudes de pago.<br>
              **Nota**: El estado puede cambiar a `inactive` si el propietario cancela o elimina el método de pago en la institución financiera.
            - `error`<br>
              La institución financiera no pudo confirmar el registro de la cuenta bancaria (generalmente debido a que el propietario proporcionó información incorrecta de la cuenta bancaria o un error en la institución financiera).
            - `inactive`<br>
              El método de pago no puede ser utilizado. Esto generalmente se debe a que el propietario canceló su cuenta y la institución financiera nos informó que el método ya no es 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: Una matriz de objetos de métodos de pago de clientes.
          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: >-
            El identificador único creado por Belvo utilizado para referenciar
            la solicitud de pago.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
        createdDate:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: >-
            La marca de tiempo ISO-8601 cuando se creó la solicitud de pago en
            la base de datos de Belvo.
          example: '2022-02-09T08:45:50.406032Z'
        lastUpdatedDate:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: >-
            La marca de tiempo ISO-8601 cuando se actualizó por última vez la
            información sobre la solicitud de pago.
          example: '2022-02-09T08:45:50.406032Z'
        status:
          type: string
          enum:
            - initial
            - processing
            - successful
            - failed
            - canceled
          description: |-
            El estado de la solicitud de pago. Puede ser uno de los siguientes:
              - `initial`<br>
                La solicitud de pago ha sido creada.
              - `processing`<br>
                Los archivos de cobro han sido generados para la solicitud de pago. Esperando respuesta de la institución financiera.
              - `successful`<br>
                La institución financiera ha confirmado la solicitud de pago y los fondos han sido transferidos.
              - `failed`<br>
                La institución financiera ha reportado un error en la solicitud de pago y no se han transferido fondos.
              - `canceled`<br>
                La solicitud fue cancelada. Esto solo es posible si la solicitud de pago no ha pasado al estado `processing`.
          example: processing
        failedReason:
          type:
            - string
            - 'null'
          description: El código de falla de la institución financiera.
          example: null
        failedReasonMessage:
          type:
            - string
            - 'null'
          description: >-
            El mensaje de falla de la institución financiera, que describe la
            razón de la falla.
          example: null
        amount:
          type: string
          description: El monto a debitar del cliente.
          example: '100000.00'
        currency:
          type: string
          enum:
            - mxn
          description: >-
            El código de moneda de tres letras ISO 4217 de la transacción. Por
            el momento, solo admitimos `mxn`.
          example: mxn
        customer:
          type: string
          format: uuid
          description: >-
            El identificador único creado por Belvo utilizado para referenciar
            al cliente.
          example: 3118128a-6792-4b06-bd61-4acf6f6ad6b5
        customerName:
          type: string
          description: El nombre del cliente.
          example: Carlos Vives
        reference:
          type: string
          minLength: 1
          maxLength: 160
          description: Una referencia para la solicitud de pago.
          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) Información sobre el préstamo asociado con la
            solicitud de pago.
          properties:
            reference:
              type: string
              maxLength: 50
              description: >-
                Su referencia para el préstamo asociado con la solicitud de
                pago.
              example: Camera Purchase 1432
            disbursementDate:
              type: string
              format: date
              description: >-
                La fecha en que se desembolsó el préstamo, en formato
                YYYY-MM-DD.
              example: '2025-01-01'
            installmentNumber:
              type: integer
              description: El número de la cuota que se está pagando.
              example: 1
            installmentAmount:
              type: number
              format: float
              pattern: ^\d{1,15}\.\d{2,4}$
              description: El monto de la cuota que se está pagando.
              example: 100.02
            installmentDueDate:
              type: string
              format: date
              description: >-
                La fecha de vencimiento de la cuota que se está pagando, en
                formato YYYY-MM-DD.
              example: '2025-03-01'
            totalAmount:
              type: number
              format: float
              pattern: ^\d{1,15}\.\d{2,4}$
              description: El monto total del préstamo.
              example: 12000.24
            totalInstallments:
              type: integer
              description: El número total de cuotas para el préstamo.
              example: 12
    payment_request_paginated:
      type: object
      properties:
        items:
          type: array
          description: Una matriz de objetos de solicitud de pago.
          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 pago existente
      description: >-
        El cuerpo de la solicitud para crear una solicitud de pago para un
        método de pago existente.
      required:
        - amount
        - currency
        - reference
        - paymentMethodId
      properties:
        amount:
          type: number
          format: float
          description: El monto a debitar del cliente.
          example: 1000
        currency:
          type: string
          enum:
            - mxn
          description: >-
            El código de moneda de tres letras ISO 4217 de la transacción. Por
            el momento, solo admitimos `mxn`.
          example: mxn
        reference:
          type: string
          minLength: 1
          maxLength: 50
          description: Su referencia interna para la solicitud de pago.
          example: J-789029-PAY-3X
        paymentMethodId:
          type: string
          format: uuid
          description: >-
            El identificador único creado por Belvo utilizado para referenciar
            el método de pago.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
        loanInformation:
          type: object
          description: >-
            (Metadata opcional) Información sobre el préstamo asociado con la
            solicitud de pago.
          properties:
            reference:
              type: string
              maxLength: 50
              description: >-
                Su referencia para el préstamo asociado con la solicitud de
                pago.
              example: Camera Purchase 1432
            disbursementDate:
              type: string
              format: date
              description: >-
                La fecha en que se desembolsó el préstamo, en formato
                YYYY-MM-DD.
              example: '2025-01-01'
            installmentNumber:
              type: integer
              description: El número de la cuota que se está pagando.
              example: 1
            installmentAmount:
              type: number
              format: float
              pattern: ^\d{1,15}\.\d{2,4}$
              description: El monto de la cuota que se está pagando.
              example: 100.02
            installmentDueDate:
              type: string
              format: date
              description: >-
                La fecha de vencimiento de la cuota que se está pagando, en
                formato YYYY-MM-DD.
              example: '2025-03-01'
            totalAmount:
              type: number
              format: float
              pattern: ^\d{1,15}\.\d{2,4}$
              description: El monto total del préstamo.
              example: 12000.24
            totalInstallments:
              type: integer
              description: El número total de cuotas para el préstamo.
              example: 12
    paymentRequestId:
      type: object
      properties:
        paymentRequestId:
          type: string
          format: uuid
          description: >-
            El identificador único creado por Belvo utilizado para referenciar
            la solicitud de pago.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    movement:
      type: object
      description: Un movimiento individual en la cuenta del cliente.
      properties:
        id:
          type: string
          format: uuid
          description: >-
            El identificador único creado por Belvo utilizado para referenciar
            el movimiento.
          example: 38848ec1-79bb-4827-87b1-819f186ad273
        createdDate:
          type: string
          format: date-time
          description: >-
            La marca de tiempo ISO-8601 cuando el movimiento fue creado en la
            base de datos de Belvo.
          example: '2025-05-14T16:20:00Z'
        lastUpdatedDate:
          type: string
          format: date-time
          description: >-
            La marca de tiempo ISO-8601 cuando se actualizó por última vez la
            información sobre el movimiento.
          example: '2025-05-14T16:25:00Z'
        chargebackDate:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            La marca de tiempo ISO-8601 de cuando la devolución de cargo fue
            iniciada por la institución bancaria (solo aplicable si el
            movimiento fue causado por una devolución de cargo (`reason` =
            `payments_service_chargeback`)).
          example: null
        type:
          type: string
          enum:
            - credit
            - debit
          description: |-
            El tipo de movimiento. Puede ser:
              - `credit` (dinero depositado en tu cuenta)
              - `debit` (dinero retirado de tu cuenta)
          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: |-
            La razón del movimiento. Puede ser:

              - `withdrawal`: El saldo fue transferido a la cuenta del comerciante.
              - `payments_service_charge`: Se realizó un cargo exitoso.
              - `payments_service_fee`: La comisión de Belvo por un cargo exitoso o fallido.
              - `payments_service_fee_tax`: El impuesto sobre la `payments_service_fee`.
              - `payments_service_chargeback`: Ocurrió un contracargo.
              - `penny_validation_fee`: La comisión de Belvo por una validación de centavos.
              - `penny_validation_fee_tax`: El impuesto sobre la `penny_validation_fee`.
              - `adjustment`: Usado en el caso de cualquier otro movimiento necesario para ajustar el saldo del comerciante.
          example: payments_service_fee
        amount:
          type: number
          format: float
          description: La cantidad del movimiento.
          example: 125.5
        currency:
          type: string
          minLength: 3
          maxLength: 3
          pattern: ^[A-Z]{3}$
          description: El código de moneda de tres letras (ISO-4217).
          example: MXN
        paymentRequest:
          type: string
          format: uuid
          description: El ID de la solicitud de pago asociada.
          example: 136771f0-13d7-4725-ae0b-e25e9055716d
        paymentRequestReference:
          type:
            - string
            - 'null'
          description: Una referencia para la solicitud de pago.
          example: INV-2025-001
        paymentRequestDisplayReference:
          type:
            - string
            - 'null'
          description: >-
            Una descripción de referencia que se muestra en el estado de cuenta
            bancario de su cliente.
          example: Payment to ACME Corp
        customerName:
          type: string
          description: El nombre del cliente asociado al movimiento.
          example: Juan Pérez
        customerDocumentType:
          type: string
          enum:
            - mx_rfc
            - mx_curp
          description: >-
            El tipo de documento del cliente. Para 🇲🇽 México, puede ser uno de
            los siguientes:
              - `mx_rfc`: Número de Identificación Fiscal (Registro Federal de Contribuyentes)
              - `mx_curp`: Clave Única de Registro de Población (Clave Única de Registro de Población)
          example: mx_rfc
        customerDocumentNumber:
          type: string
          description: El número de documento del cliente.
          example: HEGJ850506SX1
        paymentMethodType:
          type: string
          enum:
            - bank_account
          description: >-
            El tipo de método de pago. Para México, este valor se establece en
            `bank_account`.
          example: bank_account
        accountNumber:
          type: string
          description: El número de cuenta de su cliente.
          example: 12345678901234568
        withdrawalId:
          type:
            - string
            - 'null'
          description: >-
            ID interno de Belvo para movimientos donde el `reason` es
            `withdrawal`.
          example: 9e637645-efe8-4fb7-a442-fa2eeb5ad606
        withdrawalCreatedDate:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            La marca de tiempo ISO-8601 para movimientos donde el `reason` es
            `withdrawal`.
          example: '2025-05-10T14:30:00Z'
        withdrawalExtra:
          type:
            - object
            - 'null'
          description: >-
            Un objeto personalizable que contiene pares clave-valor adicionales
            que solicitaste a Belvo incluir para movimientos donde el `reason`
            es `withdrawal`.
          example:
            reference_id: ABC123
            withdrawal_method: bank_transfer
    movement_paginated:
      type: object
      properties:
        items:
          type: array
          description: Un arreglo de objetos de movimiento.
          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: >-
            El identificador único creado por Belvo utilizado para referenciar
            el consentimiento.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
        status:
          type: string
          enum:
            - awaiting_information
            - submitted
            - confirmed
            - incomplete_information
            - rejected
            - received_chargeback
          description: >-
            El estado del consentimiento. Puede ser uno de los siguientes:


            **Inicial**:

            - `awaiting_information`: El consentimiento ha sido creado y ahora
            se deben cargar los archivos acompañantes.


            **Después de cargar los archivos**:

            - `submitted`: Se han cargado todos los documentos necesarios y el
            consentimiento está pendiente de confirmación.

            - `incomplete_information`: Falta uno o más archivos o son
            inválidos.


            **Estados finales**:

            - `confirmed`: Los archivos asociados han sido revisados y
            aceptados. El consentimiento ahora está activo y puedes realizar
            solicitudes de pago.

            - `rejected`: Los documentos presentados fueron rechazados y el
            consentimiento no fue otorgado.

            - `received_chargeback`: El cliente recibió un contracargo después
            de que el consentimiento fue `confirmed`.
        paymentMethodId:
          type: string
          format: uuid
          readOnly: true
          description: >-
            El identificador único creado por Belvo utilizado para referenciar
            el método de pago.
          example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
        isBankNotified:
          type: boolean
          readOnly: true
          description: >-
            Indica si el banco ha sido notificado del Consent. Esto se establece
            en `true` en el caso de que se reciba una devolución de cargo y la
            evidencia del Consent se haya enviado al banco.
          example: false
    consent_id_file:
      type: object
      required:
        - type
        - consentFileId
        - consentId
      properties:
        type:
          type: string
          enum:
            - id_front
            - id_back
            - selfie
            - contract
          description: >-
            El tipo de archivo de Consentimiento. Puede ser uno de los
            siguientes:
              - `id_front`
              - `id_back`
              - `selfie`
              - `contract`
          example: id_front
        consentFileId:
          type: string
          format: uuid
          readOnly: true
          description: >-
            El identificador único creado por Belvo utilizado para referenciar
            el archivo de Consent.
          example: 8c56b4e7-d025-4b1a-a303-dd472b24f431
        consentId:
          type: string
          format: uuid
          readOnly: true
          description: >-
            El identificador único creado por Belvo utilizado para referenciar
            el Consent.
          example: 0494baff-3bbb-43c7-bb58-67ac6cba3e54
  parameters:
    page:
      name: page
      required: false
      in: query
      description: Un número de página dentro del conjunto de resultados paginados.
      schema:
        example: 1
        format: int32
        type: integer
    limit:
      name: limit
      required: false
      in: query
      description: >-
        Indica cuántos resultados devolver por página. Por defecto, devolvemos
        20 resultados por página.


        ℹ️ El número mínimo de resultados devueltos por página es 1 y el máximo
        es 100. Si introduces un valor mayor que 100, nuestra API usará por
        defecto el valor máximo (100).
      schema:
        type: integer
        format: int32
        default: 20
        minimum: 1
        maximum: 100
        example: 15
    search_customer:
      name: search
      required: false
      in: query
      description: >-
        Devuelve resultados que coincidan con el `email`, `firstname`,
        `lastname` o `documentNumber` que buscaste.


        **Nota:**


        Este filtro admite consultas de búsqueda tanto completas como parciales.


        Por ejemplo, buscar `car` puede coincidir con los siguientes 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: >-
        El identificador único creado por Belvo utilizado para referenciar al
        cliente.
      schema:
        type: string
        format: uuid
        example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    search__general:
      name: search
      required: false
      in: query
      description: >-
        Devuelve resultados que coincidan con la `reference` que buscaste.


        **Nota:**

        Este filtro admite consultas de búsqueda tanto completas como parciales.
        Por ejemplo, buscar `trai` puede coincidir con los siguientes valores
        (extraídos del campo `reference`):

          - `Awesome training sneakers`
          - `Training equipment`
      schema:
        type: string
        example: trai
    customer_id:
      name: customer_id
      required: false
      in: query
      description: >-
        El identificador único creado por Belvo utilizado para referenciar al
        cliente.
      schema:
        type: string
        format: uuid
        example: 0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c
    type:
      name: type
      required: false
      in: query
      description: |-
        El tipo de cuenta. Puede ser:

          - `bank_account`
            Usado para la mayoría de las cuentas bancarias.
      schema:
        type: string
        enum:
          - bank_account
        example: bank_account
    paymentMethodId:
      name: paymentMethodId
      required: true
      in: path
      description: >-
        El identificador único creado por Belvo utilizado para referenciar el
        método de pago.
      schema:
        type: string
        format: uuid
        example: d5f2e1a8-f449-4338-bd6a-df62b3fbf0b3
    order:
      name: order
      required: false
      in: query
      description: >-
        Devuelve los resultados en orden ascendente (de más antiguo a más
        reciente) o descendente (de más reciente a más antiguo), según el
        `createdDate`.


        Puede ser:
          - `asc` para orden ascendente
          - `desc` para orden descendente
      schema:
        enum:
          - asc
          - desc
        example: asc
        type: string
    start_date:
      name: start_date
      required: false
      in: query
      description: >-
        Devuelve los elementos con una `createdDate` mayor o igual a la fecha
        especificada. La fecha debe estar en el 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: >-
        Devuelve los elementos con una `createdDate` menor o igual a la fecha
        especificada. La fecha debe estar en el 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, pero altamente recomendado.) Un identificador único para esta
        solicitud para apoyar la idempotencia. Utiliza un UUID o un
        identificador similar. Para más información, consulta nuestro artículo
        dedicado a la <a
        href="https://developers.belvo.com/docs/direct-debit-idempotency-and-whitelisting"
        target="_blank">Idempotencia</a>.
      schema:
        type: string
    paymentRequestId:
      name: paymentRequestId
      required: true
      in: path
      description: >-
        El identificador único creado por Belvo utilizado para referenciar la
        solicitud de pago.
      schema:
        type: string
        format: uuid
        example: 2e66d035-c78f-435c-a21d-b86d3e7b351d
    from_created_date:
      name: from_created_date
      in: query
      description: >-
        Filtrar movimientos creados en o después de esta fecha, en formato
        `YYYY-MM-DD`.
      required: false
      schema:
        type: string
        format: date
    until_created_date:
      name: until_created_date
      in: query
      description: >-
        Filtrar movimientos creados en o antes de esta fecha, en formato
        `YYYY-MM-DD`.
      required: false
      schema:
        type: string
        format: date
    type_movement:
      name: type
      in: query
      description: Filtrar movimientos por uno de estos tipos (`credit` o `debit`).
      required: false
      schema:
        type: string
        enum:
          - credit
          - debit
    withdrawal_id:
      name: withdrawal_id
      in: query
      description: Filtrar movimientos por este ID de retiro.
      required: false
      schema:
        type: string
    reason:
      name: reason
      in: query
      description: |-
        Filtrar movimientos por una o más de las siguientes razones:
        - 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
