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/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: 4bf92b25-f457-447d-bfb5-a185e9ffe3e3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePrivateAccountRequest'
      responses:
        '201':
          description: Private account created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateAccountResponse'
  /v1/owners/{clientId}/instruments:
    post:
      operationId: postCreateInstrument
      summary: Create a new instrument
      security:
        - bearerAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
            example: c2d1d1e3-3340-4170-980e-e9269bbbc551
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInstrumentRequest'
      responses:
        '200':
          description: Successful creation of private account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInstrumentResponse'
  /v1/transactions/money_out:
    post:
      operationId: createMoneyOutTransaction
      summary: Create a money out transaction
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoneyOutRequest'
            example:
              client_id: c2d1d1e3-3340-4170-980e-e9269bbbc551
              source_instrument_id: b5a3e093-4b78-45b8-9be0-dec8b1bff5a1
              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: d3435bd9-998d-4e8a-9067-6b71d5fd3ac7
                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/webhooks:
    post:
      summary: Register a webhook
      description: Endpoint to register a new url where to receive webhooks.
      operationId: createWebhook
      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
      responses:
        '201':
          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: Get notified about new MONEY_IN events.
      security:
        - bearerAuth: []
      operationId: webhookMoneyInPost
      description: Send MONEY_IN webhook event notification.
      requestBody:
        description: Information about a new Money IN event.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookMoneyInEvent'
      responses:
        '200':
          description: Webhook received successfully
  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'
components:
  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: d90bde89-d3b9-476b-9ce4-6d5633966011
        owner_id:
          type: string
          format: uuid
          example: 4bf92b25-f457-447d-bfb5-a185e9ffe3e3
        client_bank_adapter_id:
          type: string
          format: uuid
          example: 4bb0d00c-ce4a-4b65-9848-fa973ae785b3
        client_id:
          type: string
          format: uuid
          example: 4bf92b25-f457-447d-bfb5-a185e9ffe3e3
        account_id:
          type: string
          format: uuid
          example: 9df37c0a-ef5a-4e95-a5f9-cc0103e2edb6
    CreateInstrumentRequest:
      type: object
      properties:
        bank_id:
          type: string
          example: 3054ff18-32a0-478d-b9fe-b5261f9a6e1f
        client_id:
          type: string
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        instrument_alias:
          type: string
          example: Instrumento A
        instrument_type:
          type: string
          example: SENDER_RECEIVER
        rfc:
          type: string
          example: ND
        virtual_clabe:
          type: object
          properties:
            bank_id:
              type: string
              example: 3054ff18-32a0-478d-b9fe-b5261f9a6e1f
            account_number:
              type: string
              example: ''
            clabe_number:
              type: string
              example: '646180000000001801'
            holder_name:
              type: string
              example: John Smith
    MoneyOutRequest:
      type: object
      properties:
        client_id:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        source_instrument_id:
          type: string
          format: uuid
          example: b5a3e093-4b78-45b8-9be0-dec8b1bff5a1
        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
          example: MONEY_IN
    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: string
          nullable: true
          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: string
          nullable: true
          example: None
    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: 1934444f-d0bb-4bb4-94d9-b13bc7c487d1
        bankId:
          type: string
          format: uuid
          example: d3435bd9-998d-4e8a-9067-6b71d5fd3ac7
        clientId:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        clientBankAdapterId:
          type: string
          format: uuid
          example: b7b89b2a-161a-46df-9d60-a60e26aea4d9
        accountId:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        instrumentId:
          type: string
          format: uuid
          example: b5a3e093-4b78-45b8-9be0-dec8b1bff5a1
        ownerId:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        ownerType:
          type: string
          enum:
            - CLIENT
            - BUSINESS
          example: CLIENT
        accountNumber:
          type: string
          example: '999900000004'
        clabeNumber:
          type: string
          example: '646189999900000004'
        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: STP
    PrivateAccountResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 4c3093a6-2e6c-4637-8d58-f27d5f639176
        bankId:
          type: string
          format: uuid
          example: d3435bd9-998d-4e8a-9067-6b71d5fd3ac7
        clientId:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        clientBankAdapterId:
          type: string
          format: uuid
          example: b7b89b2a-161a-46df-9d60-a60e26aea4d9
        accountId:
          type: string
          format: uuid
          example: 1934444f-d0bb-4bb4-94d9-b13bc7c487d1
        instrumentId:
          type: string
          format: uuid
          example: 6ad80330-31bc-410c-93e1-3fbbc5401a53
        ownerId:
          type: string
          format: uuid
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        ownerType:
          type: string
          example: CLIENT
        accountNumber:
          type: string
          example: '999909456345'
        clabeNumber:
          type: string
          example: '646189999909456345'
        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-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: string
              nullable: true
              example: None
            blockedAt:
              type: string
              nullable: true
              example: None
            activatedAt:
              type: string
              nullable: true
              example: None
            suspendedAt:
              type: string
              nullable: true
              example: None
        bankAdapter:
          type: string
          example: STP
    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: string
          nullable: true
          example: None
        blockedAt:
          type: string
          nullable: true
          example: None
        activatedAt:
          type: string
          nullable: true
          example: None
        suspendedAt:
          type: string
          nullable: true
          example: None
    CreateInstrumentResponse:
      type: object
      properties:
        id:
          type: string
          example: d3fdb481-2058-46c8-807d-4eaf866ae1ec
        bankId:
          type: string
          example: 3054ff18-32a0-478d-b9fe-b5261f9a6e1f
        clientId:
          type: string
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        ownerId:
          type: string
          example: c2d1d1e3-3340-4170-980e-e9269bbbc551
        instrumentAlias:
          type: string
          example: Instrumento A
        instrumentStatus:
          type: string
          example: ACTIVE
        instrumentType:
          type: string
          example: SENDER_RECEIVER
        instrumentDetail:
          type: object
          properties:
            accountNumber:
              type: string
              example: None
            clabeNumber:
              type: string
              example: '646180000000001801'
            holderName:
              type: string
              example: John Smith
        audit:
          type: object
          properties:
            createdAt:
              type: string
              format: date-time
              example: '2025-03-05 18:54:04.127190-06:00'
            updatedAt:
              type: string
              format: date-time
              example: '2025-03-05 18:54:04.127190-06:00'
            deletedAt:
              type: string
              nullable: true
              example: None
            blockedAt:
              type: string
              nullable: true
              example: None
        rfc:
          type: string
          example: ND
    MoneyOutResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 16811ee8-1ef9-4dd4-8d84-9c2df89cf302
        bankId:
          type: string
          format: uuid
          example: d3435bd9-998d-4e8a-9067-6b71d5fd3ac7
        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: string
              nullable: true
              example: None
            blockedAt:
              type: string
              nullable: true
              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: string
          nullable: true
          example: None
        blockedAt:
          type: string
          nullable: true
          example: None
        deletedBy:
          type: string
          nullable: true
          example: None
        blockedBy:
          type: string
          nullable: true
          example: None
    WebhookMoneyInEvent:
      type: object
      properties:
        id_msg:
          type: string
          format: uuid
          example: a7a126e8-fa74-411c-ad2b-b000f277bb0d
        msg_name:
          type: string
          example: MONEY_IN
        msg_date:
          type: string
          format: date-time
          example: '2025-04-02'
        body:
          type: object
          properties:
            id:
              type: string
              format: uuid
              example: '1595465866'
            beneficiary_account:
              type: string
              example: '646180529600044117'
            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
              example: '40002'
            amount:
              type: string
              example: '123.00'
            transaction_date:
              type: string
              format: date-time
              example: '20250402'
            tracking_key:
              type: string
              example: 50118609TBRNZ00I07219647
            payment_concept:
              type: string
              example: Payment for invoice 4567
            numeric_reference:
              type: string
              example: '2504021'
    StatusUpdateMessage:
      type: object
      properties:
        id_msg:
          type: string
          format: uuid
          example: 1b3b4567-e89b-12d3-a456-426600174000
        msg_name:
          type: string
          example: STATUS_UPDATE
        msg_date:
          type: string
          format: date-time
          example: '2025-03-05T10:26:01Z'
        body:
          type: object
          properties:
            tracking_key:
              type: string
              example: 20250305FINCH9AAX30000I
            status:
              type: string
              enum:
                - INITIALIZED
                - IN_PROGRESS
                - LIQUIDATED
                - CANCELED
                - REFUND
                - REJECTED
                - DECLINED
              example: LIQUIDATED
            update_at:
              type: string
              format: date-time
              example: '2025-03-05T10:26:01.161000'
  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:
  - ApiKey: []
