openapi: 3.0.3
info:
  title: Tazama Transaction Monitoring Service Health Transaction Evaluation 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: Transaction Evaluation
  description: ISO 20022 transaction message evaluation for fraud and AML detection
paths:
  /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:
    Unauthorized:
      description: Unauthorized - Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad Request - Invalid message format or missing required fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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
    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
    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
    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
    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