openapi: 3.0.3
info:
  title: Mono Connect API
  description: 'A grounded subset of the Mono open banking API for Africa. Mono lets businesses link customer bank accounts and read financial data, assess creditworthiness, collect direct bank payments (DirectPay), and verify identity (Lookup). Server-to-server requests authenticate with a secret key sent in the `mono-sec-key` header. Account linking is completed by the customer through the hosted Mono Connect widget; the widget returns a short-lived authorization code that is exchanged for a permanent account id used on all financial-data calls.


    Endpoint paths and methods here are grounded in the public Mono documentation at docs.mono.co (base host `https://api.withmono.com`, most endpoints under `/v2`; the account-number and Mashup Lookup endpoints are under `/v3`). Request and response bodies are modeled representatively - treat field-level schemas as illustrative and confirm exact payloads against the live reference before relying on them.'
  version: '2.0'
  contact:
    name: Mono
    url: https://mono.co
  x-provenance: Endpoint paths/methods grounded in docs.mono.co (2026-07-12). Request/response schemas are modeled and should be reconciled against the live API reference.
servers:
- url: https://api.withmono.com
  description: Mono production API host
security:
- monoSecKey: []
tags:
- name: Connect
  description: Account linking authorization and re-authorization.
paths:
  /v2/accounts/initiate:
    post:
      operationId: initiateAccountLinking
      tags:
      - Connect
      summary: Initiate account linking
      description: Starts an account-linking session for the Mono Connect widget. Returns a session that the customer uses to authorize access to their bank account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateRequest'
      responses:
        '200':
          description: A linking session was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiateResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/accounts/auth:
    post:
      operationId: exchangeToken
      tags:
      - Connect
      summary: Exchange token
      description: Exchanges the authorization code returned by the Connect widget for a permanent account id. Store the returned id to make future financial-data calls for this account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthRequest'
      responses:
        '200':
          description: The authorization code was exchanged for an account id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    InitiateResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        data:
          type: object
          properties:
            mono_url:
              type: string
            customer:
              type: string
            meta:
              type: object
    Error:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
    InitiateRequest:
      type: object
      properties:
        customer:
          type: object
          description: Customer details for the linking session.
        meta:
          type: object
          description: Arbitrary metadata echoed back on the linked account.
        scope:
          type: string
          description: The linking scope, e.g. `auth`.
        redirect_url:
          type: string
    AuthResponse:
      type: object
      properties:
        id:
          type: string
          description: The permanent account id for the linked account.
    AuthRequest:
      type: object
      required:
      - code
      properties:
        code:
          type: string
          description: The authorization code returned by the Connect widget.
  responses:
    Unauthorized:
      description: The `mono-sec-key` is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    monoSecKey:
      type: apiKey
      in: header
      name: mono-sec-key
      description: Secret key for the application, found in the Mono dashboard. Sent on every server-to-server request in the `mono-sec-key` header. Use test keys in the sandbox and live keys in production.