openapi: 3.0.3
info:
  title: Tazama Transaction Monitoring Service API
  description: >-
    The Tazama Transaction Monitoring Service (TMS) API ingests real-time ISO 20022
    financial transaction messages for fraud detection and AML compliance. Supports
    pain.001, pain.013, pacs.008, and pacs.002 message types from financial service
    providers including banks, remitters, mobile money operators, clearing houses,
    and payment switches. The service validates messages, routes them through
    configurable rule processors, and returns fraud and AML evaluation results.
  version: 0.1.0
  contact:
    name: Tazama
    url: https://tazama.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: http://localhost:5000
    description: Local Development Server
tags:
  - name: Health
    description: Service health check operations
  - name: Transaction Evaluation
    description: ISO 20022 transaction message evaluation for fraud and AML detection
paths:
  /:
    get:
      operationId: getServiceStatus
      summary: Get Service Status
      description: Check if the Transaction Monitoring Service is up and running correctly.
      tags:
        - Health
      responses:
        '200':
          description: Service is up and running
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /health:
    get:
      operationId: getHealthStatus
      summary: Get Health Status
      description: Check the health status of the Transaction Monitoring Service.
      tags:
        - Health
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/evaluate/iso20022/pain.001.001.11:
    post:
      operationId: evaluatePain001Transaction
      summary: Evaluate Pain 001 Transaction
      description: >-
        Evaluates an ISO 20022 pain.001.001.11 formatted message (Customer Credit
        Transfer Initiation). Historically corresponds to a Mojaloop Quote message.
        Validates the message and initiates real-time fraud and AML rule processing.
      tags:
        - Transaction Evaluation
      requestBody:
        required: true
        description: ISO 20022 pain.001.001.11 customer credit transfer initiation message
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ISO20022Pain001'
            example:
              CstmrCdtTrfInitn:
                GrpHdr:
                  MsgId: "8cc4f6ffb4fd4e31b42aec0ed5d600a0123"
                  CreDtTm: "2021-10-07T09:25:31.000Z"
                  NbOfTxs: 1
                  InitgPty:
                    Nm: "Ivan Reese Russel-Klein"
                PmtInf:
                  PmtInfId: "8cc4f6ffb4fd4e31b42aec0ed5d600a0123"
                  PmtMtd: "TRA"
      responses:
        '200':
          description: Transaction evaluated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/evaluate/iso20022/pain.013.001.09:
    post:
      operationId: evaluatePain013Transaction
      summary: Evaluate Pain 013 Transaction
      description: >-
        Evaluates an ISO 20022 pain.013.001.09 formatted message (Creditor Payment
        Activation Request). Historically corresponds to a Mojaloop Quote Response
        message. Validates the message and initiates real-time fraud and AML rule
        processing.
      tags:
        - Transaction Evaluation
      requestBody:
        required: true
        description: ISO 20022 pain.013.001.09 creditor payment activation request message
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ISO20022Pain013'
            example:
              CdtrPmtActvtnReq:
                GrpHdr:
                  MsgId: "8cc4f6ffb4fd4e31b42aec0ed5d600a0123"
                  CreDtTm: "2021-10-07T09:25:31.000Z"
                  NbOfTxs: 1
      responses:
        '200':
          description: Transaction evaluated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/evaluate/iso20022/pacs.008.001.10:
    post:
      operationId: evaluatePacs008Transaction
      summary: Evaluate Pacs 008 Transaction
      description: >-
        Evaluates an ISO 20022 pacs.008.001.10 formatted message (Financial Institution
        to Financial Institution Customer Credit Transfer). Historically corresponds to
        a Mojaloop Transfer message. Validates the message and initiates real-time
        fraud and AML rule processing.
      tags:
        - Transaction Evaluation
      requestBody:
        required: true
        description: ISO 20022 pacs.008.001.10 FI to FI customer credit transfer message
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ISO20022Pacs008'
            example:
              FIToFICstmrCdtTrf:
                GrpHdr:
                  MsgId: "8cc4f6ffb4fd4e31b42aec0ed5d600a0123"
                  CreDtTm: "2021-11-09T09:25:31.000Z"
                  NbOfTxs: 1
                  SttlmInf:
                    SttlmMtd: "CLRG"
      responses:
        '200':
          description: Transaction evaluated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/evaluate/iso20022/pacs.002.001.12:
    post:
      operationId: evaluatePacs002Transaction
      summary: Evaluate Pacs 002 Transaction
      description: >-
        Evaluates an ISO 20022 pacs.002.001.12 formatted message (Financial Institution
        to Financial Institution Payment Status Report). Validates the message and
        initiates real-time fraud and AML rule processing.
      tags:
        - Transaction Evaluation
      requestBody:
        required: true
        description: ISO 20022 pacs.002.001.12 payment status report message
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ISO20022Pacs002'
            example:
              FIToFIPmtSts:
                GrpHdr:
                  MsgId: "8cc4f6ffb4fd4e31b42aec0ed5d600a0123"
                  CreDtTm: "2021-09-13T15:56:49.000Z"
                TxInfAndSts:
                  TxSts: "ACSC"
      responses:
        '200':
          description: Transaction evaluated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    BadRequest:
      description: Bad Request - Invalid message format or missing required fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Health:
      type: object
      description: Service health status response
      properties:
        status:
          type: string
          enum:
            - UP
            - DOWN
          description: Current service status
          example: UP
    TransactionResponse:
      type: object
      description: Response returned after evaluating a transaction message
      properties:
        message:
          type: string
          description: Human-readable evaluation result message
          example: Transaction is valid
        data:
          type: object
          description: Additional evaluation data including rule results and typology scores
          additionalProperties: true
    Error:
      type: object
      description: Error response
      properties:
        data:
          type: object
          properties:
            error:
              type: string
              description: Error message description
    ISO20022Pain001:
      type: object
      description: >-
        ISO 20022 pain.001.001.11 Customer Credit Transfer Initiation message.
        Used for initiating credit transfers from a debtor to one or more creditors.
      required:
        - CstmrCdtTrfInitn
      properties:
        CstmrCdtTrfInitn:
          type: object
          description: Customer Credit Transfer Initiation
          properties:
            GrpHdr:
              type: object
              description: Group Header
              properties:
                MsgId:
                  type: string
                  minLength: 1
                  maxLength: 35
                  example: '8cc4f6ffb4fd4e31b42aec0ed5d600a0123'
                CreDtTm:
                  type: string
                  format: date-time
                  example: '2021-10-07T09:25:31.000Z'
                NbOfTxs:
                  type: integer
                  example: 1
                InitgPty:
                  type: object
                  description: Initiating Party
                  properties:
                    Nm:
                      type: string
                      maxLength: 140
                      example: 'Ivan Reese Russel-Klein'
            PmtInf:
              type: object
              description: Payment Information
              properties:
                PmtInfId:
                  type: string
                  minLength: 1
                  maxLength: 35
                  example: '8cc4f6ffb4fd4e31b42aec0ed5d600a0123'
                PmtMtd:
                  type: string
                  example: 'TRA'
                Dbtr:
                  type: object
                  description: Debtor
                  properties:
                    Nm:
                      type: string
                      maxLength: 140
                      example: 'Ivan Reese Russel-Klein'
                DbtrAcct:
                  type: object
                  description: Debtor Account
                  properties:
                    Id:
                      type: object
                      properties:
                        Othr:
                          type: object
                          properties:
                            Id:
                              type: string
                              maxLength: 35
                              example: '+27783078685'
                DbtrAgt:
                  type: object
                  description: Debtor Agent
                  properties:
                    FinInstnId:
                      type: object
                      properties:
                        ClrSysMmbId:
                          type: object
                          properties:
                            MmbId:
                              type: string
                              maxLength: 36
                              example: 'dfsp001'
    ISO20022Pain013:
      type: object
      description: >-
        ISO 20022 pain.013.001.09 Creditor Payment Activation Request message.
        Used by creditors to request payment initiation from debtors.
      required:
        - CdtrPmtActvtnReq
      properties:
        CdtrPmtActvtnReq:
          type: object
          description: Creditor Payment Activation Request
          properties:
            GrpHdr:
              type: object
              description: Group Header
              properties:
                MsgId:
                  type: string
                  minLength: 1
                  maxLength: 35
                  example: '8cc4f6ffb4fd4e31b42aec0ed5d600a0123'
                CreDtTm:
                  type: string
                  format: date-time
                  example: '2021-10-07T09:25:31.000Z'
                NbOfTxs:
                  type: integer
                  example: 1
    ISO20022Pacs002:
      type: object
      description: >-
        ISO 20022 pacs.002.001.12 Financial Institution to Financial Institution
        Payment Status Report message.
      required:
        - FIToFIPmtSts
      properties:
        FIToFIPmtSts:
          type: object
          description: FI to FI Payment Status
          required:
            - GrpHdr
          properties:
            GrpHdr:
              type: object
              required:
                - MsgId
                - CreDtTm
              properties:
                MsgId:
                  type: string
                  minLength: 1
                  maxLength: 35
                  example: '8cc4f6ffb4fd4e31b42aec0ed5d600a0123'
                CreDtTm:
                  type: string
                  format: date-time
                  example: '2021-09-13T15:56:49.000Z'
            TxInfAndSts:
              type: object
              description: Transaction Information and Status
              properties:
                OrgnlInstrId:
                  type: string
                  maxLength: 35
                  example: '8cc4f6ffb4fd4e31b42aec0ed5d600a0123'
                OrgnlEndToEndId:
                  type: string
                  maxLength: 35
                  example: '8cc4f6ffb4fd4e31b42aec0ed5d600a0123'
                TxSts:
                  type: string
                  enum:
                    - ACCC
                    - ACCP
                    - ACFC
                    - ACSC
                    - ACSP
                    - ACTC
                    - ACWC
                    - ACWP
                    - BLCK
                    - CANC
                    - PATC
                    - PDNG
                    - PRES
                    - RCVD
                    - RJCT
                  example: ACSC
    ISO20022Pacs008:
      type: object
      description: >-
        ISO 20022 pacs.008.001.10 Financial Institution to Financial Institution
        Customer Credit Transfer message.
      required:
        - FIToFICstmrCdtTrf
      properties:
        FIToFICstmrCdtTrf:
          type: object
          description: FI to FI Customer Credit Transfer
          required:
            - GrpHdr
          properties:
            GrpHdr:
              type: object
              required:
                - MsgId
                - CreDtTm
                - NbOfTxs
                - SttlmInf
              properties:
                MsgId:
                  type: string
                  minLength: 1
                  maxLength: 35
                  example: '8cc4f6ffb4fd4e31b42aec0ed5d600a0123'
                CreDtTm:
                  type: string
                  format: date-time
                  example: '2021-11-09T09:25:31.000Z'
                NbOfTxs:
                  type: integer
                  example: 1
                SttlmInf:
                  type: object
                  required:
                    - SttlmMtd
                  properties:
                    SttlmMtd:
                      type: string
                      minLength: 4
                      maxLength: 4
                      example: 'CLRG'
            CdtTrfTxInf:
              type: object
              description: Credit Transfer Transaction Information
              properties:
                PmtId:
                  type: object
                  properties:
                    InstrId:
                      type: string
                      maxLength: 35
                      example: '8cc4f6ffb4fd4e31b42aec0ed5d600a0123'
                    EndToEndId:
                      type: string
                      maxLength: 35
                      example: '8cc4f6ffb4fd4e31b42aec0ed5d600a0123'
                Dbtr:
                  type: object
                  description: Debtor
                  properties:
                    Nm:
                      type: string
                      maxLength: 140
                      example: 'Ivan Reese Russel-Klein'
                Cdtr:
                  type: object
                  description: Creditor
                  properties:
                    Nm:
                      type: string
                      maxLength: 140
                ChrgBr:
                  type: string
                  example: 'DEBT'