openapi: 3.1.0
info:
  version: 1.0.0
  title: Fincore API
  description: >-
    Monato is a financial technology company specializing in SPEI transfer
    services in Mexico. We provide secure, fast, and reliable payment solutions
    for businesses, enabling seamless bank transfers through our API and
    platform
servers:
  - url: https://apicore.stg.finch.lat
paths:
  /v1/clients/{clientId}/credentials:
    get:
      summary: Retrieve client credentials
      description: Returns a list of credentials associated with a specific client.
      operationId: getClientCredentials
      security:
        - ApiKeyAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          description: The unique identifier of the client.
          schema:
            type: string
            format: uuid
            example: c2d1d1e3-3340-4170-980e-e9269bbbc551
      responses:
        '200':
          description: A list of client credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialsResponse'
  /v1/clients/{clientId}/auth/credential-tokens:
    post:
      operationId: createCredentialToken
      summary: Create authentication token
      description: Generates an authentication credential token for a private account.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier for the client.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthCredentialRequest'
      responses:
        '200':
          description: Successfully created credential token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthCredentialResponse'
  /v1/banks:
    get:
      operationId: retrieveBanksCatalog
      summary: Retrieve catalog of SPEI participants
      description: >-
        Returns a paginated list of bank and institutions that are part of the
        SPEI Network.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: A list of institutions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BanksResponse'
              examples:
                example:
                  value:
                    total_banks: 1
                    page: 1
                    page_size: 50
                    banks:
                      - id: 9d84b03a-28d1-4898-a69c-38824239e2b1
                        name: FINCO_PAY
                        token: '734'
                        BIM: '734'
                        code: '90734'
                        bank_status: ACTIVE
  /v1/clients/{clientId}/accounts:
    get:
      operationId: getAccounts
      summary: Retrieve accounts for a client
      description: Returns a paginated list of accounts for the specified client.
      security:
        - bearerAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          description: Unique identifier of the client
          schema:
            type: string
      responses:
        '200':
          description: Successful response with account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountsResponse'
  /v1/clients/{clientId}/private_accounts:
    post:
      operationId: postCreatePrivateAccount
      summary: Create a private account
      description: Endpoint to create a private account for a client.
      security:
        - bearerAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          description: Unique identifier of the client.
          schema:
            type: string
            format: uuid
            example: c2d1d1e3-3340-4170-980e-e9269bbbc551
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePrivateAccountRequest'
      responses:
        '200':
          description: Private account created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateAccountResponse'
  /v1/clients/{clientId}/instruments/{instrumentId}:
    get:
      operationId: getInstrumentById
      summary: Retrieve a single instrument
      description: >
        Retrieves an instrument for the specified client. The instrument must
        belong to the client or to one of its customers; otherwise an error is
        returned.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: clientId
          required: true
          description: Client identifier (UUID).
          schema:
            type: string
            format: uuid
        - in: path
          name: instrumentId
          required: true
          description: Instrument identifier (UUID).
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Instrument details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstrumentResponse'
        '404':
          description: Instrument not found for this client.
  /v1/clients/{clientId}/instruments:
    get:
      operationId: listInstruments
      summary: List instruments for a client
      description: >
        Returns a paginated list of instruments belonging to the specified
        client and its customers.

        - Without `customer_id`, it returns instruments for the client and all
        associated customers.

        - With `customer_id`, it returns only instruments for that customer.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: clientId
          required: true
          description: Client identifier (UUID).
          schema:
            type: string
            format: uuid
        - in: query
          name: customer_id
          required: false
          description: >-
            Optional customer UUID. When provided, filters instruments for this
            customer only.
          schema:
            type: string
            format: uuid
        - in: query
          name: page
          required: false
          description: Page number (1-based).
          schema:
            type: integer
            minimum: 1
        - in: query
          name: per_page
          required: false
          description: Number of items per page.
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: >-
            List of instruments for the client (and optionally a specific
            customer).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstrumentsResponse'
        '400':
          description: 'Client not found (DATA_ERROR - "No client found for id: ...").'
        '404':
          description: >-
            Customer not found or not associated to this client
            (RESOURCE_NOT_FOUND - "Customer not found").
    post:
      summary: Register an instrument for a client
      description: >
        Registers an instrument owned by the specified client or by one of its
        customers.

        The request body must include either `debit_card` or `virtual_clabe`..
      operationId: registerInstrument
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: clientId
          required: true
          description: >
            Client identifier (UUID) under which the instrument is being
            registered. The actual owner will be: - The client itself, if
            `customer_id` is omitted in the request body. - The customer
            specified in `customer_id`, if provided.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/RegisterDebitCardRequest'
                - $ref: '#/components/schemas/RegisterClabeRequest'
              discriminator:
                propertyName: instrumentKind
                mapping:
                  debit_card: '#/components/schemas/RegisterDebitCardRequest'
                  virtual_clabe: '#/components/schemas/RegisterClabeRequest'
            examples:
              addDebitCard:
                summary: Add debit card
                value:
                  source_bank_id: 9d84b03a-28d1-4898-a69c-38824239e2b1
                  client_id: c2d1d1e3-3340-4170-980e-e9269bbbc551
                  customer_id: bb1e8fde-e68e-48e9-a483-d32153c752c2
                  type: RECEIVER
                  rfc: XAXX010101000
                  alias: Tarjeta ABC123
                  debit_card:
                    destination_bank_id: 3054ff18-32a0-478d-b9fe-b5261f9a6e1f
                    card_number: '5579072268574100'
                    holder_name: Pedro Navajas Dos
              addClabe:
                summary: Add CLABE
                value:
                  source_bank_id: 9d84b03a-28d1-4898-a69c-38824239e2b1
                  client_id: c2d1d1e3-3340-4170-980e-e9269bbbc551
                  type: RECEIVER
                  rfc: XAXX010101000
                  alias: CLABE XYZ123
                  virtual_clabe:
                    destination_bank_id: 3054ff18-32a0-478d-b9fe-b5261f9a6e1f
                    account_number: '006487113111'
                    clabe_number: '002118006487113111'
                    holder_name: Pedro Navajas Perez
      responses:
        '200':
          description: Instrument created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstrumentResponse'
              examples:
                createdCard:
                  summary: Created debit card instrument
                  value:
                    id: dd7f8d89-94dd-43ca-871b-720fde378b52
                    bankId: d3435bd9-998d-4e8a-9067-6b71d5fd3ac7
                    clientId: c2d1d1e3-3340-4170-980e-e9269bbbc551
                    ownerId: c2d1d1e3-3340-4170-980e-e9269bbbc551
                    alias: Tarjeta con expiracion
                    type: RECEIVER
                    instrumentDetail:
                      cardNumber: '5579072268574100'
                      expirationDate: None
                      holderName: Pedro Navajas Dos
                    audit:
                      createdAt: '2025-05-19 19:03:51.084659-06:00'
                      updatedAt: '2025-05-19 19:03:51.084659-06:00'
                      deletedAt: None
                      blockedAt: None
                    rfc: XAXX010101000
                    customerId: bb1e8fde-e68e-48e9-a483-d32153c752c2
                createdClabe:
                  summary: Created CLABE instrument
                  value:
                    id: 2e7e36f8-d3ba-48a0-872e-f093379d6a4f
                    bankId: 3054ff18-32a0-478d-b9fe-b5261f9a6e1f
                    clientId: c2d1d1e3-3340-4170-980e-e9269bbbc551
                    ownerId: c2d1d1e3-3340-4170-980e-e9269bbbc551
                    alias: CLABE XYZ123
                    type: RECEIVER
                    instrumentDetail:
                      accountNumber: '006487113111'
                      clabeNumber: '002118006487113111'
                      holderName: Pedro Navajas Perez
                    audit:
                      createdAt: '2025-08-11 13:52:21.702839-06:00'
                      updatedAt: '2025-08-11 13:52:21.702839-06:00'
                      deletedAt: None
                      blockedAt: None
                    rfc: XAXX010101000
  /v1/transactions/money_out:
    post:
      operationId: createMoneyOutTransaction
      summary: Create a money out transaction
      description: >
        Initiate an outbound transfer. This endpoint supports Idempotency via
        the `Idempotency-Key` header (TTL: 24h). Reuse the same key with the
        exact same body for safe retries. See the Idempotency guide for
        details. 
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoneyOutRequest'
            example:
              client_id: c2d1d1e3-3340-4170-980e-e9269bbbc551
              source_instrument_id: 709448c3-7cbf-454d-a87e-feb23801269a
              destination_instrument_id: d3fdb481-2058-46c8-807d-4eaf866ae1ec
              transaction_request:
                external_reference: '1234567'
                description: lorem ipsum dolor sit amet
                amount: '1.95'
                currency: MXN
      responses:
        '200':
          description: Successfully created transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MoneyOutResponse'
              example:
                id: 16811ee8-1ef9-4dd4-8d84-9c2df89cf302
                bankId: 9d84b03a-28d1-4898-a69c-38824239e2b1
                clientId: c2d1d1e3-3340-4170-980e-e9269bbbc551
                externalReference: '1234567'
                trackingId: 20250306FINCHVLIKQ5SKUM
                description: lorem ipsum dolor sit amet
                amount: '1.95'
                currency: MXN
                category: DEBIT_TRANS
                subCategory: SPEI_DEBIT
                transactionStatus: INITIALIZED
                audit:
                  createdAt: '2025-03-06 11:57:55.408000-06:00'
                  updatedAt: '2025-03-06 11:57:55.408000-06:00'
                  deletedAt: None
                  blockedAt: None
  /v1/clients/{clientId}/transactions/{transactionId}/refund:
    post:
      summary: Refund a transaction
      description: >-
        Creates a refund for a transaction. Partial refunds are not allowed. The
        `amount` must equal the original transaction amount received.
      operationId: createRefund
      security:
        - bearerAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          description: >-
            Client UUID (must match the client_id embedded in the Authorization
            token).
          schema:
            type: string
            format: uuid
        - name: transactionId
          in: path
          required: true
          description: Transaction UUID to be refunded.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
            example:
              amount: '5.00'
              description: Invalid Amount
      responses:
        '200':
          description: Refund successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
              example:
                id: 957459ce-d4e3-40b5-b759-373e844ba1e8
                bankId: 9d84b03a-28d1-4898-a69c-38824239e2b1
                clientId: c2d1d1e3-3340-4170-980e-e9269bbbc551
                externalReference: '2505091'
                trackingId: 20250510FINCHFL2SFGP9KT
                description: lorem ipsum dolor sit amet
                amount: '100.00'
                currency: MXN
                category: DEBIT_TRANS
                subCategory: SPEI_DEBIT
                transactionStatus: INITIALIZED
                audit:
                  createdAt: '2025-05-09 18:02:31.979746-06:00'
                  updatedAt: '2025-05-09 18:02:31.979746-06:00'
                  deletedAt: null
                  blockedAt: null
  /v1/webhooks:
    post:
      summary: Register a webhook
      description: Endpoint to register a new url where to receive webhooks.
      operationId: createWebhook
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
            example:
              client_id: '{{clientId}}'
              url: https://example.com/webhook
              token: secretToken0123
              webhook_type: MONEY_IN
              auth_type: AUTH
      responses:
        '200':
          description: Webhook successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
              example:
                id: 29806117-2b15-4682-87f0-350e6695fe91
                clientId: c2d1d1e3-3340-4170-980e-e9269bbbc551
                url: https://example.com/webhook
                token: secretToken0123
                webhookType: MONEY_IN
                webhookStatus: ACTIVE
                createdAt: '2025-04-03 13:40:54.056794-06:00'
                updatedAt: '2025-04-03 13:40:54.056794-06:00'
                deletedAt: None
                blockedAt: None
                deletedBy: None
                blockedBy: None
webhooks:
  money-in:
    post:
      summary: MONEY_IN webhook event.
      security:
        - bearerAuth: []
      operationId: webhookMoneyInPost
      description: >
        Monato sends this webhook to notify you about new Money In events into
        your accounts. The payload covers both external SPEI credits and
        internal credits (book-to-book). Use fields such as `sub_category` and
        `payer_institution` to distinguish between them.
      requestBody:
        description: Information about a new Money IN event.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookMoneyInEvent'
      responses:
        '200':
          description: >
            Money In notification received successfully. Treated as a technical
            acknowledgement (equivalent to 201).
        '201':
          description: >
            Money In notification received and accepted. Recommended status code
            when you accept the Money In (SPEI credits).
        '202':
          description: >
            Money In notification received successfully; extra validations will
            be done asynchronously on your side.
        '422':
          description: >
            Money In notification received, but not accepted. For external SPEI
            credits, Monato will automatically refund the transaction to the
            original source. Not applicable to internal Money In (`INT_CREDIT`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MoneyInRejectionResponse'
              example:
                refundReason: Invalid amount
  status-update:
    post:
      summary: Get notified about Status updates.
      security:
        - bearerAuth: []
      operationId: webhookStatusUpdatePost
      description: Send Status updates for Money Outs
      requestBody:
        description: Information about new status
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusUpdateMessage'
  cep:
    post:
      summary: Get notified about CEP updates (Penny Validation)
      security:
        - bearerAuth: []
      operationId: webhookCepPost
      description: >
        Sends CEP status updates for Penny Validation: PENDING, DELAYED,
        COMPLETED, or FAILED. Note: `INITIALIZED` is never emitted by the
        webhook (it may appear on API reads only and should be treated as
        PENDING).
      requestBody:
        description: CEP status notification payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCepEvent'
      responses:
        '200':
          description: CEP notification received and accepted
        '202':
          description: >-
            CEP notification received; additional validations will be done
            asynchronously
        '422':
          description: CEP notification received, but not accepted
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >
        Client-generated deterministic UUID v5 derived from (client_id + method
        + body_hash) within an environment-specific namespace. When present, the
        first response (success or error) is cached for 24h; identical retries
        (same key + same body) return the same cached response. If the body
        changes with the same key, the server returns 409 Conflict.
      schema:
        type: string
        pattern: >-
          ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-5[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
  schemas:
    AuthCredentialRequest:
      type: object
      required:
        - client_id
        - client_secret
      properties:
        client_id:
          type: string
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        client_secret:
          type: string
          example: your_client_secret_here
    CreatePrivateAccountRequest:
      type: object
      required:
        - bank_id
        - owner_id
        - client_bank_adapter_id
        - client_id
        - account_id
      properties:
        bank_id:
          type: string
          format: uuid
          example: 9d84b03a-28d1-4898-a69c-38824239e2b1
        owner_id:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        client_bank_adapter_id:
          type: string
          format: uuid
          example: 5b3a1b67-ab59-4cc1-8fc6-1d558b32b237
        client_id:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        account_id:
          type: string
          format: uuid
          example: 24a726ac-180d-48df-82bc-711f2788a46f
    MoneyOutRequest:
      type: object
      properties:
        client_id:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        source_instrument_id:
          type: string
          format: uuid
          example: 709448c3-7cbf-454d-a87e-feb23801269a
        destination_instrument_id:
          type: string
          format: uuid
          example: d3fdb481-2058-46c8-807d-4eaf866ae1ec
        transaction_request:
          type: object
          properties:
            external_reference:
              type: string
              example: '1234567'
            description:
              type: string
              example: lorem ipsum dolor sit amet
            amount:
              type: string
              example: '1.95'
            currency:
              type: string
              example: MXN
    CreateWebhookRequest:
      type: object
      required:
        - client_id
        - url
        - token
        - webhook_type
      properties:
        client_id:
          type: string
          example: '{{clientId}}'
        url:
          type: string
          format: uri
          example: https://example.com/webhook
        token:
          type: string
          example: secretToken0123
        webhook_type:
          type: string
          enum:
            - MONEY_IN
            - STATUS_UPDATE
            - CEP
          example: CEP
    RefundRequest:
      type: object
      properties:
        amount:
          type: string
          description: >-
            Refund amount (full refund only) — must be exactly equal to the
            original transaction amount received. Use two decimal places.
          example: '10.00'
        description:
          type: string
          description: Text with the refund reason
          example: Invalid amount
    RefundResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 957459ce-d4e3-40b5-b759-373e844ba1e8
        bankId:
          type: string
          format: uuid
          example: 9d84b03a-28d1-4898-a69c-38824239e2b1
        clientId:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        externalReference:
          type: string
          example: '2505091'
        trackingId:
          type: string
          example: 20250510FINCHFL2SFGP9KT
        description:
          type: string
          example: lorem ipsum dolor sit amet
        amount:
          type: string
          format: decimal
          example: '100.00'
        currency:
          type: string
          example: MXN
        category:
          type: string
          example: DEBIT_TRANS
        subCategory:
          type: string
          example: SPEI_DEBIT
        transactionStatus:
          type: string
          example: INITIALIZED
        audit:
          type: object
          properties:
            createdAt:
              type: string
              format: date-time
              example: '2025-05-09 18:02:31.979746-06:00'
            updatedAt:
              type: string
              format: date-time
              example: '2025-05-09 18:02:31.979746-06:00'
            deletedAt:
              type:
                - 'null'
                - string
              format: date-time
              example: null
            blockedAt:
              type:
                - 'null'
                - string
              format: date-time
              example: null
    MoneyInRejectionResponse:
      type: object
      properties:
        refundReason:
          type: string
          description: >-
            Text with the reason why you reject the Money In. Used to populate
            the SPEI refund concept.
          example: Invalid amount
      required:
        - refundReason
    CredentialsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Credential'
    Credential:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the credential.
          example: e981c6d8-4d49-45f2-a7ee-f956dca15500
        client_id:
          type: string
          format: uuid
          description: The unique identifier of the client.
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        client_secret:
          type: string
          description: The secret key for the client.
          example: >-
            Ui9gx7AXIpRqSkwSMQ35Ag1N5NXvm_7e4OEZESNMLQ29SbsvsXI1KKfIsGlZ70h_DfIPX2EWlysRlEKz8bXMsA
        environment:
          type: string
          enum:
            - staging
            - production
          description: The environment in which the credentials are valid.
          example: staging
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          description: The status of the credentials.
          example: ACTIVE
        created_at:
          type: string
          format: date-time
          description: Timestamp when the credentials were created.
          example: '2025-03-05T10:27:36.888241-06:00'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the credentials were last updated.
          example: '2025-03-05T10:27:36.888241-06:00'
        deleted_at:
          type:
            - 'null'
            - string
          description: >-
            Timestamp when the credentials were deleted, or null if still
            active.
          example: None
    AuthCredentialResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 1307f4e3-3960-4b98-9a14-0b6839245cc9
        client_id:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        client_credential_id:
          type: string
          format: uuid
          example: e981c6d8-4d49-45f2-a7ee-f956dca15500
        token:
          type: string
          description: JWT authentication token
          example: >-
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJjMmQxZDFlMy0zMzQwLTQxNzAtOTgwZS1lOTI2OWJiYmM1NTEiLCJleHAiOjE3NDEyODE0MTl9.ziSqMClLqwUVfyM15bqUF_7-PINY0ZiWkH01s8pO3gA
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          example: ACTIVE
        expires_at:
          type: string
          format: date-time
          example: '2025-03-06 11:16:59.491631'
        created_at:
          type: string
          format: date-time
          example: '2025-03-05 11:16:59.488685-06:00'
        updated_at:
          type: string
          format: date-time
          example: '2025-03-05 11:16:59.488685-06:00'
        deleted_at:
          type:
            - 'null'
            - string
          example: None
    BanksResponse:
      type: object
      properties:
        total_banks:
          type: integer
          example: 2
        page:
          type: integer
          example: 1
        page_size:
          type: integer
          example: 50
        banks:
          type: array
          items:
            $ref: '#/components/schemas/Bank'
    Bank:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 9d84b03a-28d1-4898-a69c-38824239e2b1
        name:
          type: string
          example: FINCO_PAY
        token:
          type: string
          example: '734'
        BIM:
          type: string
          example: '734'
        code:
          type: string
          example: '90734'
        bank_status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          example: ACTIVE
    InstrumentsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/InstrumentResponse'
        currentPage:
          type: integer
          example: 1
        perPage:
          type: integer
          example: 50
        totalItems:
          type: integer
          example: 17
      required:
        - data
        - currentPage
        - perPage
        - totalItems
    AccountsResponse:
      type: object
      properties:
        currentPage:
          type: integer
          example: 1
        perPage:
          type: integer
          example: 50
        totalItem:
          type: integer
          example: 1
        data:
          type: array
          items:
            $ref: '#/components/schemas/Account'
    Account:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 24a726ac-180d-48df-82bc-711f2788a46f
        bankId:
          type: string
          format: uuid
          example: 9d84b03a-28d1-4898-a69c-38824239e2b1
        clientId:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        clientBankAdapterId:
          type: string
          format: uuid
          example: 5b3a1b67-ab59-4cc1-8fc6-1d558b32b237
        accountId:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        instrumentId:
          type: string
          format: uuid
          example: 709448c3-7cbf-454d-a87e-feb23801269a
        ownerId:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        ownerType:
          type: string
          enum:
            - CLIENT
            - BUSINESS
          example: CLIENT
        accountNumber:
          type: string
          example: '000001000004'
        clabeNumber:
          type: string
          example: '734180000001000004'
        availableBalance:
          type: string
          example: '0.00'
        accountType:
          type: string
          enum:
            - CENTRALIZING_ACCOUNT
            - OTHER
          example: CENTRALIZING_ACCOUNT
        accountStatus:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
            - SUSPENDED
          example: ACTIVE
        audit:
          $ref: '#/components/schemas/Audit'
        bankAdapter:
          type: string
          example: SIES
    PrivateAccountResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 750ab428-b401-4b58-8a95-502bcb7b1bf8
        bankId:
          type: string
          format: uuid
          example: 9d84b03a-28d1-4898-a69c-38824239e2b1
        clientId:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        clientBankAdapterId:
          type: string
          format: uuid
          example: 5b3a1b67-ab59-4cc1-8fc6-1d558b32b237
        accountId:
          type: string
          format: uuid
          example: 24a726ac-180d-48df-82bc-711f2788a46f
        instrumentId:
          type: string
          format: uuid
          example: ab502fce-1162-42f3-99d6-972989a06049
        ownerId:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        ownerType:
          type: string
          example: CLIENT
        accountNumber:
          type: string
          example: '000001233635'
        clabeNumber:
          type: string
          example: '734180000001233635'
        availableBalance:
          type: string
          example: '0.00'
        accountType:
          type: string
          example: PRIVATE_ACCOUNT
        accountStatus:
          type: string
          example: ACTIVE
        audit:
          type: object
          properties:
            createdAt:
              type: string
              format: date-time
              example: '2025-04-12 11:00:56.264527-06:00'
            updatedAt:
              type: string
              format: date-time
              example: '2025-04-12 11:00:56.264527-06:00'
            deletedAt:
              type:
                - 'null'
                - string
              example: None
            blockedAt:
              type:
                - 'null'
                - string
              example: None
            activatedAt:
              type:
                - 'null'
                - string
              example: None
            suspendedAt:
              type:
                - 'null'
                - string
              example: None
        bankAdapter:
          type: string
          example: SIES
    Audit:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          example: '2025-03-05 11:00:56.264527-06:00'
        updatedAt:
          type: string
          format: date-time
          example: '2025-03-05 11:00:56.264527-06:00'
        deletedAt:
          type:
            - 'null'
            - string
          example: None
        blockedAt:
          type:
            - 'null'
            - string
          example: None
        activatedAt:
          type:
            - 'null'
            - string
          example: None
        suspendedAt:
          type:
            - 'null'
            - string
          example: None
    MoneyOutResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 16811ee8-1ef9-4dd4-8d84-9c2df89cf302
        bankId:
          type: string
          format: uuid
          example: 9d84b03a-28d1-4898-a69c-38824239e2b1
        clientId:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        externalReference:
          type: string
          example: '1234567'
        trackingId:
          type: string
          example: 20250306FINCHVLIKQ5SKUM
        description:
          type: string
          example: lorem ipsum dolor sit amet
        amount:
          type: string
          example: '1.95'
        currency:
          type: string
          example: MXN
        category:
          type: string
          example: DEBIT_TRANS
        subCategory:
          type: string
          example: SPEI_DEBIT
        transactionStatus:
          type: string
          example: INITIALIZED
        audit:
          type: object
          properties:
            createdAt:
              type: string
              format: date-time
              example: '2025-03-06 11:57:55.408000-06:00'
            updatedAt:
              type: string
              format: date-time
              example: '2025-03-06 11:57:55.408000-06:00'
            deletedAt:
              type:
                - 'null'
                - string
              example: None
            blockedAt:
              type:
                - 'null'
                - string
              example: None
    WebhookResponse:
      type: object
      properties:
        id:
          type: string
          example: 29806117-2b15-4682-87f0-350e6695fe91
        clientId:
          type: string
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        url:
          type: string
          example: https://example.com/webhook
        token:
          type: string
          example: secretToken0123
        webhookType:
          type: string
          example: MONEY_IN
        webhookStatus:
          type: string
          example: ACTIVE
        createdAt:
          type: string
          format: date-time
          example: '2025-04-03 13:40:54.056794-06:00'
        updatedAt:
          type: string
          format: date-time
          example: '2025-04-03 13:40:54.056794-06:00'
        deletedAt:
          type:
            - 'null'
            - string
          example: None
        blockedAt:
          type:
            - 'null'
            - string
          example: None
        deletedBy:
          type:
            - 'null'
            - string
          example: None
        blockedBy:
          type:
            - 'null'
            - string
          example: None
    WebhookMoneyInEvent:
      type: object
      properties:
        id_msg:
          type: string
          format: uuid
          description: Unique message identifier (use for idempotency/deduplication).
          example: a7a126e8-fa74-411c-ad2b-b000f277bb0d
        msg_name:
          type: string
          description: Event name. For Money In notifications it is always "MONEY_IN".
          example: MONEY_IN
        msg_date:
          type: string
          format: date
          description: Event date (YYYY-MM-DD).
          example: '2025-04-02'
        body:
          type: object
          properties:
            id:
              type: string
              format: uuid
              example: 0196da9a-8947-703e-9a3b-bf8c7d9f6059
            beneficiary_account:
              type: string
              example: '734180123045603216'
            beneficiary_name:
              type: string
              example: John Smith
            beneficiary_rfc:
              type: string
              example: XYZ123456789
            payer_account:
              type: string
              example: '137180210044008609'
            payer_name:
              type: string
              example: Juan Perez
            payer_rfc:
              type: string
              example: XYZ987654321
            payer_institution:
              type: string
              description: >
                SPEI: Banxico institution code of the originating bank (e.g.
                40002). Internal: Monato internal institution code (e.g. 90734).
              example: '40002'
            amount:
              type: string
              description: Amount credited, with two decimal places.
              example: '123.00'
            transaction_date:
              type: string
              description: >
                Date and time when the transaction was registered in the rail.
                Format: YYYY-MM-DD HH:MM:SS.
              example: '2025-04-02 10:14:05'
            tracking_key:
              type: string
              example: 50118609TBRNZ00I07219647
            payment_concept:
              type: string
              example: Payment for invoice 4567
            numeric_reference:
              type: string
              example: '2504021'
            sub_category:
              type: string
              description: |
                Internal classification of the credit. Typical values:
                  - SPEI_CREDIT – external SPEI credit.
                  - INT_CREDIT – internal credit from internal_transaction.
              example: SPEI_CREDIT
            registered_at:
              type: string
              format: date-time
              description: >-
                Timestamp in Monato when the transaction was created / persisted
                (ISO-8601 with timezone).
              example: '2025-04-02T10:14:05.915184-06:00'
            owner_id:
              type: string
              format: uuid
              description: >-
                Identifier of the owner of the destination instrument (e.g. the
                customer that owns the receiving account).
              example: 24f1e5d5-4045-4b1a-a0c4-5e6c6b1d44ef
      required:
        - id_msg
        - msg_name
        - msg_date
        - body
    WebhookCepEvent:
      type: object
      properties:
        id_msg:
          type: string
          format: uuid
          description: Unique message identifier (use for idempotency/deduplication)
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        msg_name:
          type: string
          description: Event name
          enum:
            - CEP
          example: CEP
        msg_date:
          type: string
          format: date
          description: Event date (YYYY-MM-DD)
          example: '2025-08-15'
        body:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: Transaction ID for the penny validation
              example: 11111111-2222-3333-4444-555555555555
            tracking_key:
              type: string
              example: 20250815XXXXXX123456789
            beneficiary_account:
              type: string
              description: CLABE of the beneficiary
              example: '000000000000000000'
            beneficiary_name:
              type: string
              example: Daniela Paola Santelices Chavez
            beneficiary_rfc:
              type:
                - string
                - 'null'
              example: XXXX000000XXX
            status:
              type: string
              description: CEP processing status
              enum:
                - PENDING
                - DELAYED
                - COMPLETED
                - FAILED
              example: DELAYED
            processed_at:
              type:
                - string
                - 'null'
              format: date-time
              description: Timestamp when CEP was finalized (COMPLETED/FAILED)
              example: '2025-08-15T22:42:39.327Z'
      required:
        - id_msg
        - msg_name
        - msg_date
        - body
    StatusUpdateMessage:
      type: object
      properties:
        id_msg:
          type: string
          format: uuid
          example: 35066b9c-e1e3-4d1b-89e6-35c036a70b00
        msg_name:
          type: string
          example: STATUS_UPDATE
        msg_date:
          type: string
          format: date
          example: '2025-08-27'
        body:
          type: object
          properties:
            id:
              type: string
              format: uuid
              example: 6fd78718-106c-485d-824d-f6c3e8133571
            tracking_key:
              type: string
              example: 20250827FINCH5CJS56XDFE
            message_type:
              type: string
              example: SPEI
            reason:
              type: string
              example: CANCELLED_ACCOUNT
            reason_description:
              type: string
              example: Cuenta cancelada
            status:
              type: string
              enum:
                - INITIALIZED
                - LIQUIDATED
                - REFUND
                - REJECTED
              example: REJECTED
            update_at:
              type: string
              format: date-time
              example: '2025-08-27T15:40:44.413078-06:00'
    RegisterInstrumentBase:
      type: object
      properties:
        source_bank_id:
          type: string
          description: Issuer/processing bank ID at Finco/Finch.
          example: 9d84b03a-28d1-4898-a69c-38824239e2b1
        client_id:
          type: string
          description: >
            Client UUID under which the instrument is being registered. The
            actual owner will be the client itself (if `customer_id` is omitted)
            or the customer specified in `customer_id` (if provided).
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        customer_id:
          type: string
          description: >
            Optional customer UUID that will own the instrument. When provided,
            the instrument belongs to this customer.
          example: bb1e8fde-e68e-48e9-a483-d32153c752c2
        type:
          type: string
          enum:
            - RECEIVER
          description: Instrument usage type. Currently only `RECEIVER` is accepted.
          example: RECEIVER
        rfc:
          type: string
          description: >
            RFC tax identifier of the account or card holder. If you don't have
            it, you can send "ND".
          example: XAXX010101000
        alias:
          type: string
          description: Human-friendly label for the instrument.
          example: lorem-ipsum
      required:
        - source_bank_id
        - client_id
        - type
        - rfc
        - alias
      additionalProperties: false
    RegisterDebitCardRequest:
      allOf:
        - $ref: '#/components/schemas/RegisterInstrumentBase'
        - type: object
          properties:
            debit_card:
              $ref: '#/components/schemas/DebitCardPayload'
          required:
            - debit_card
          additionalProperties: false
    RegisterClabeRequest:
      allOf:
        - $ref: '#/components/schemas/RegisterInstrumentBase'
        - type: object
          properties:
            virtual_clabe:
              $ref: '#/components/schemas/VirtualClabePayload'
          required:
            - virtual_clabe
          additionalProperties: false
    DebitCardPayload:
      type: object
      properties:
        destination_bank_id:
          type: string
          example: 3054ff18-32a0-478d-b9fe-b5261f9a6e1f
        card_number:
          type: string
          example: '5579072268574100'
        holder_name:
          type: string
          example: John Smith
      required:
        - destination_bank_id
        - card_number
        - holder_name
      additionalProperties: false
    VirtualClabePayload:
      type: object
      properties:
        destination_bank_id:
          type: string
          example: 3054ff18-32a0-478d-b9fe-b5261f9a6e1f
        account_number:
          type: string
          example: '006487113111'
        clabe_number:
          type: string
          example: '002118006487113111'
        holder_name:
          type: string
          example: John Smith
      required:
        - destination_bank_id
        - account_number
        - clabe_number
        - holder_name
      additionalProperties: false
    InstrumentResponse:
      allOf:
        - $ref: '#/components/schemas/InstrumentBaseResponse'
        - type: object
          properties:
            instrumentDetail:
              oneOf:
                - $ref: '#/components/schemas/CardInstrumentDetail'
                - $ref: '#/components/schemas/ClabeInstrumentDetail'
          required:
            - instrumentDetail
    InstrumentBaseResponse:
      type: object
      properties:
        id:
          type: string
          example: dd7f8d89-94dd-43ca-871b-720fde378b52
        bankId:
          type: string
          example: d3435bd9-998d-4e8a-9067-6b71d5fd3ac7
        clientId:
          type: string
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        ownerId:
          type: string
          description: >
            Identifier of the entity that owns this instrument (client or
            customer). When the instrument belongs to a customer, `ownerId` and
            `customerId` will be the same.
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        alias:
          type: string
          example: Instrumento base
        type:
          type: string
          enum:
            - RECEIVER
          example: RECEIVER
        audit:
          type: object
          properties:
            createdAt:
              type: string
              example: '2025-05-19 19:03:51.084659-06:00'
            updatedAt:
              type: string
              example: '2025-05-19 19:03:51.084668-06:00'
            deletedAt:
              type:
                - string
                - 'null'
              example: null
            blockedAt:
              type:
                - string
                - 'null'
              example: null
          required:
            - createdAt
            - updatedAt
            - deletedAt
            - blockedAt
        rfc:
          type: string
          example: XAXX010101000
        customerId:
          type: string
          description: >
            Customer who owns the instrument when applicable. Present when the
            instrument belongs to a customer; omitted for client-level
            instruments.
          example: bb1e8fde-e68e-48e9-a483-d32153c752c2
      required:
        - id
        - bankId
        - clientId
        - ownerId
        - alias
        - type
        - audit
        - rfc
      additionalProperties: false
    CardInstrumentDetail:
      type: object
      properties:
        cardNumber:
          type: string
          example: '5579072268574100'
        expirationDate:
          type:
            - string
            - 'null'
          description: May be the string "None" or null when not available.
          example: None
        holderName:
          type: string
          example: John Smith
      required:
        - cardNumber
        - holderName
      additionalProperties: false
    ClabeInstrumentDetail:
      type: object
      properties:
        accountNumber:
          type: string
          example: '006487113111'
        clabeNumber:
          type: string
          example: '002118006487113111'
        holderName:
          type: string
          example: John Smith
      required:
        - accountNumber
        - clabeNumber
        - holderName
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API Key authentication using the "x-api-key" header. Contact us at
        support@monato.com so we can provide you an API Key.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - ApiKeyAuth: []
