Finero Integrations API

openapi: 3.2.0
info:
  title: Finero Public Integrations API
  version: 1.0.0
  description: 'Tenant-scoped public API for Finero — AR / cash-flow automation. Authenticate every request with `Authorization: Bearer ` (keys are created in Settings → API and are tenant-owned). All data belongs to the key''s tenant; no request input can address another tenant. Two permissions exist: **admin** keys can call every operation; **readonly** keys only operations without side effects (`x-permission: readonly`). Lists are cursor-paginated (limit 1–100, follow pagination.next_cursor). Request bodies are capped at 64 KiB. Rate limits: 120/min per key and 600/min per tenant, in fixed windows of 60 s and 60 s. The per-tenant budget is ONE budget per workspace, shared by all its API keys AND its MCP agent connections (each agent connection has its own per-credential limit, the key''s). Heavy operations (`x-heavy: true`: summarizeAging, listCustomerAging, listAgingInstallments, summarizeInvoices) read the whole book on every call and also count against 10 per 10 seconds per tenant (60 a minute, in a short window so they cannot arrive in a large burst). EVERY response that reached the limiter carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (seconds until the window resets) and `RateLimit-Policy` (every quota that applies to the operation — the heavy one too on a heavy operation; static per operation), plus the same figures as the newer combined `RateLimit` field. Pace against them rather than waiting to be refused. The triple describes whichever quota is CLOSEST TO REFUSING (on a 429, the one that refused), so a key that is fine may still show little headroom when the tenant is busy. The counters are shared server-side, not per-instance, so the numbers are exact rather than approximate. Requests rejected BEFORE the limiter — unknown path, wrong method, oversized body, missing/invalid/revoked credentials, a workspace without API access — consume no quota and carry no rate-limit fields. 429 adds `Retry-After` in seconds (RFC 9110); waiting that long is enough, and retrying sooner is refused again. Missing and invalid credentials are limited separately per source IP; that quota is deliberately not published. The windows are FIXED rather than sliding, so a burst spanning a boundary can pass up to twice the limit before being refused — do not treat the limit as a hard ceiling over less than two windows. `RateLimit-Remaining` RISES when a window rolls, for the same reason; an increase is the quota refilling, not an error. Watch `RateLimit-Reset` jump upward to tell a roll from a miscount. A 503 is not the limiter: under extreme concurrency the platform sheds load before the request reaches Finero, so it carries neither rate-limit fields nor Retry-After. Back off and retry. Decimal money amounts are exact strings (never floats); *_minor amounts are integers in the currency''s minor unit. Timestamps are ISO 8601 UTC. **There is a second way in.** This API is for systems and unattended automation, authenticated by a tenant API key that acts as the WORKSPACE. If instead a person is present and connecting an AI assistant to their own workspace, use the Finero MCP server at `https://app.getfinero.com/mcp` — Model Context Protocol over the Streamable HTTP transport (JSON-RPC 2.0, `MCP-Protocol-Version` 2026-07-28, 2025-11-25), authorized with OAuth 2.1 so the session acts as THAT PERSON. Its `server.json` manifest — the MCP registry''s published format — is at `https://app.getfinero.com/mcp/server.json`. It is read-mostly — 24 tools (list_tasks, dismiss_task, summarize_aging, list_customer_aging, list_aging_installments, list_invoices, summarize_invoices, get_invoice, list_payment_integrations, list_payments, list_workflows, list_workflow_executions, list_erp_connections, list_sync_runs, get_sync_run, start_erp_sync, list_payment_links, get_payment_link, create_payment_links, list_scheduled_emails, update_scheduled_email, delete_scheduled_email, push_payment_receipts, deactivate_payment_link).'
servers:
- url: https://api.getfinero.com/functions/v1/api
security:
- apiKey: []
tags:
- name: Integrations
paths:
  /v1/payment-integrations:
    get:
      operationId: listPaymentIntegrations
      summary: List the payment processors that collect for this workspace
      description: 'Which payment service provider Finero charges through, and how it is configured — environment, account and checkout methods. CONFIGURATION ONLY: credentials, credential masks, provider metadata, publishable keys and provider account ids are deliberately never returned. Read `environment` before reporting any collected figure: a test integration takes no real money.


        Available to **admin and readonly** API keys (no side effects).'
      tags:
      - Integrations
      security:
      - apiKey: []
      x-permission: readonly
      x-side-effects: false
      parameters:
      - name: limit
        in: query
        required: false
        description: Page size, 1–100. Default 25.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: cursor
        in: query
        required: false
        description: Opaque pagination cursor from a previous response's pagination.next_cursor.
        schema:
          type: string
          minLength: 1
          maxLength: 400
      - name: order
        in: query
        required: false
        description: 'Sort direction. Ordering is ALWAYS by when the record was CREATED in Finero, never by when it changed — `updated_since` narrows the set but does not reorder it, so the most recently updated row is not necessarily first. Creation time is immutable, which is what lets the cursor stay stable: ordering by a value that changes would move a row mid-walk and make a page skip or repeat it. Default desc (newest first by creation time).'
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: include_total
        in: query
        required: false
        description: 'Return pagination.total_count — the number of rows matching the filters, ignoring paging. It is the SAME number on every page, including alongside a cursor. Off by default: an exact count scans the whole filtered set, so asking on each page pays repeatedly for an answer that does not change — ask on the first request and keep it.'
        schema:
          type: boolean
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Payment processors, newest first by creation time.
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Integration id.
                        provider:
                          type: string
                          description: Which processor collects the money — the payment service provider Finero charges through.
                        status:
                          type: string
                          description: Whether Finero can currently charge through it.
                          enum:
                          - connected
                          - error
                          - disconnected
                        environment:
                          type:
                          - string
                          - 'null'
                          description: 'TEST or LIVE. Read this before reporting any collected figure: a test integration takes no real money, and a number sourced from one is not revenue.'
                          enum:
                          - test
                          - live
                          - null
                        account_name:
                          type:
                          - string
                          - 'null'
                          description: The processor account's own name, as the provider reports it.
                        checkout_payment_methods:
                          type:
                          - string
                          - 'null'
                          description: 'Which methods the hosted checkout offers: card_only (cards only, plus Apple Pay and Google Pay where the customer''s device supports them), or whatever the provider dashboard is configured to allow. Null for a provider without that setting (Wix).'
                        last_verified_at:
                          type:
                          - string
                          - 'null'
                          description: When Finero last confirmed the credentials work.
                        connected_at:
                          type: string
                          description: When the integration was created.
                      required:
                      - id
                      - provider
                      - status
                      - environment
                      - account_name
                      - checkout_payment_methods
                      - last_verified_at
                      - connected_at
                      additionalProperties: false
                  pagination:
                    type: object
                    properties:
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: Opaque cursor for the next page — pass as ?cursor=. Null when there are no further results.
                      has_more:
                        type: boolean
                        description: Whether another page exists.
                      limit:
                        type: integer
                        description: The page size that was applied.
                      total_count:
                        type: integer
                        description: Total rows matching the filters, ignoring paging. Present ONLY when the request passed ?include_total=true.
                    required:
                    - next_cursor
                    - has_more
                    - limit
                    additionalProperties: false
                required:
                - data
                - pagination
                additionalProperties: false
              example:
                data:
                - id: aa11bb22-cc33-4d44-8e55-ff6677889900
                  provider: stripe
                  status: connected
                  environment: test
                  account_name: Acme Industries
                  checkout_payment_methods: stripe_dashboard
                  last_verified_at: '2026-07-14T06:59:31+00:00'
                  connected_at: '2026-06-02T10:00:00+00:00'
                pagination:
                  next_cursor: null
                  has_more: false
                  limit: 25
        '400':
          description: '`invalid_cursor` — The cursor is malformed, was issued for a different query, or (aging) the report changed. Restart without cursor, keeping the filters identical. `validation_failed` — The request failed schema validation. See error.details for field messages.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: '`invalid_credentials` — The credential is malformed or does not match an active key. The response never reveals whether a key identifier exists. `missing_credentials` — No Authorization: Bearer header was sent. `revoked_credentials` — The presented key was revoked. Create a new key in Settings → API.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: '`feature_unavailable` — The tenant''s tier does not currently include API access. Feature rollout flags cannot grant this entitlement. `permission_denied` — The key''s permission does not allow this operation (readonly keys cannot call admin-only operations).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`not_found` — No such resource in YOUR tenant. Ids belonging to another tenant are indistinguishable from missing ones.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: '`rate_limit_exceeded` — Too many requests — for this key, for the workspace (one budget shared by all its API keys and MCP agent connections), or, on a heavy operation, for the workspace''s heavy budget. Honor the Retry-After header (seconds) before retrying — waiting that long is enough. The RateLimit-* fields on every response say how much headroom is left before this happens; pace against them instead of retrying into a refusal.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: '`internal_error` — Unexpected server error. Safe to retry with the same Idempotency-Key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          type: object
          required:
          - code
          - message
          - request_id
          additionalProperties: false
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
              enum:
              - missing_credentials
              - invalid_credentials
              - revoked_credentials
              - feature_unavailable
              - permission_denied
              - not_found
              - invalid_cursor
              - validation_failed
              - conflict
              - link_already_covered
              - link_not_withdrawable
              - payment_link_deactivated
              - idempotency_key_required
              - idempotency_conflict
              - rate_limit_exceeded
              - payload_too_large
              - method_not_allowed
              - installment_not_collectible
              - amount_exceeds_available
              - sync_disabled
              - connection_disconnected
              - integration_unavailable
              - currency_not_supported
              - internal_error
            message:
              type: string
              description: Human-readable explanation.
            request_id:
              type: string
              description: Echo of X-Request-Id — include it when reporting problems.
            details:
              type: array
              description: Field-level validation messages (validation_failed only).
              items:
                type: object
                required:
                - field
                - message
                properties:
                  field:
                    type: string
                  message:
                    type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'A Finero API key (`fnr_…`), created by a tenant admin in Settings → API. Sent as `Authorization: Bearer fnr_…`. Never place keys in URLs.'
      x-permissions:
        supported:
        - admin
        - readonly
        operationField: x-permission
        description: 'Each operation declares the LEAST key permission that may call it in `x-permission`. An `admin` key satisfies every operation; a `readonly` key satisfies only operations whose `x-permission` is `readonly`. The router enforces this from the same classification this document is generated from — the check is never inferred from the HTTP method. These are key PERMISSIONS, not OAuth scopes: this scheme is HTTP bearer, and OpenAPI declares `scopes` only on `oauth2`/`openIdConnect` schemes. Finero''s OAuth surface is the MCP server, which publishes RFC 9728 protected-resource metadata at `https://app.getfinero.com/mcp/.well-known/oauth-protected-resource`. Access there is granted on a consent screen, where a person lets the agent act as them, and every call is checked against that person''s own permissions — not by OAuth scope values; the authorization server accepts only `openid`.'
externalDocs:
  description: Agent-facing orientation, including the MCP server and how to connect one.
  url: https://app.getfinero.com/llms.txt