{
  "openapi": "3.0.2",
  "info": {
    "title": "Transaction Monitoring",
    "version": "",
    "description": "API for ingesting and evaluating backend-to-backend transaction events (such as payments and transfers) for real-time risk scoring and decisioning."
  },
  "servers": [
    {
      "url": "https://api.sbx.transmitsecurity.io/risk/v1",
      "description": "Sandbox environment"
    },
    {
      "url": "https://api.transmitsecurity.io/risk/v1",
      "description": "US production environment"
    },
    {
      "url": "https://api.eu.transmitsecurity.io/risk/v1",
      "description": "EU production environment"
    },
    {
      "url": "https://api.ca.transmitsecurity.io/risk/v1",
      "description": "CA production environment"
    },
    {
      "url": "https://api.au.transmitsecurity.io/risk/v1",
      "description": "AU production environment"
    },
    {
      "url": "https://api.gasne1-ts01.transmitsecurity.io/risk/v1",
      "description": "JP production environment"
    }
  ],
  "paths": {
    "/transaction-monitoring/evaluate": {
      "post": {
        "operationId": "TransactionMonitoringController_evaluate",
        "summary": "Evaluate a transaction",
        "description": "Submit a backend transaction for real-time risk evaluation and receive a recommendation (`TRUST`, `ALLOW`, `CHALLENGE`, or `DENY`) together with the transaction action token and evaluation context.",
        "security": [
          {
            "risk_access_token": []
          }
        ],
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransactionEvaluationDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transaction evaluated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TriggerTransactionResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseDto"
                }
              }
            }
          },
          "401": {
            "description": "Invalid authentication",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseDto"
                }
              }
            }
          },
          "403": {
            "description": "Invalid authorization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseDto"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseDto"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseDto"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "TransactionEvaluationDto": {
        "type": "object",
        "properties": {
          "transaction_data": {
            "$ref": "#/components/schemas/TransactionDataDto"
          },
          "custom_attributes": {
            "type": "object",
            "description": "Custom attributes add context to an action but must match the schema defined in the Portal. Invalid attributes are ignored.",
            "additionalProperties": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                }
              ]
            }
          },
          "correlation_id": {
            "type": "string",
            "description": "Any ID that could help relate the action with external context or session",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "minLength": 1,
            "maxLength": 255
          }
        },
        "required": [
          "transaction_data"
        ]
      },
      "TriggerTransactionResponseDto": {
        "type": "object",
        "properties": {
          "action_token": {
            "type": "string",
            "description": "The token returned when the transaction event was reported.",
            "example": "ea49707f023f48d64a7a817a2e7a5ff4277281a8f8ac1848ccac407967d9d2ce"
          },
          "recommendation": {
            "$ref": "#/components/schemas/TransactionRecommendationDto"
          }
        },
        "required": [
          "action_token",
          "recommendation"
        ]
      },
      "ErrorResponseDto": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number"
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "object"
          }
        },
        "required": [
          "statusCode",
          "error",
          "message"
        ]
      },
      "TransactionDataDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Type of transaction",
            "enum": [
              "purchase",
              "bill_payment",
              "mobile_recharge",
              "money_transfer",
              "credit_transfer",
              "credit_redemption",
              "top_up",
              "withdrawal",
              "investment",
              "loan",
              "refund",
              "other"
            ],
            "example": "purchase"
          },
          "method": {
            "type": "string",
            "description": "Method used for the transaction",
            "enum": [
              "bank_account",
              "wire",
              "card",
              "p2p",
              "wallet"
            ],
            "example": "card"
          },
          "reason": {
            "type": "string",
            "description": "The reason for the transaction",
            "example": "Monthly subscription payment",
            "minLength": 1,
            "maxLength": 200
          },
          "amount": {
            "type": "number",
            "description": "The monetary amount of the transaction. The backend sanitizes this value with parseFloat; it must be strictly positive and ≤ 999,999,999.99",
            "example": 1500.75
          },
          "currency": {
            "type": "string",
            "description": "The transaction currency (ISO-4217)",
            "example": "USD"
          },
          "payer": {
            "$ref": "#/components/schemas/PayerDto"
          },
          "payee": {
            "$ref": "#/components/schemas/PayeeDto"
          },
          "channelId": {
            "type": "string",
            "description": "Identifier for the channel used for the transaction",
            "example": "MOBILE_APP",
            "minLength": 1,
            "maxLength": 100
          },
          "transactionDate": {
            "type": "number",
            "description": "The transaction timestamp (Unix epoch in milliseconds or seconds). Must be a non-negative integer.",
            "example": 1712594340000,
            "minimum": 0
          },
          "purchase": {
            "$ref": "#/components/schemas/PurchaseDto"
          },
          "avs": {
            "$ref": "#/components/schemas/AvsDto"
          }
        }
      },
      "TransactionRecommendationDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Recommendation identifier"
          },
          "issued_at": {
            "type": "number",
            "description": "Unix epoch time in milliseconds this recommendation was issued at"
          },
          "recommendation": {
            "$ref": "#/components/schemas/RecommendationDTO"
          },
          "risk_score": {
            "type": "number",
            "description": "Used to assess the risk level of the client action",
            "minimum": 0,
            "maximum": 100
          },
          "context": {
            "$ref": "#/components/schemas/TransactionRecommendationContextDto"
          },
          "reasons": {
            "description": "Explains the reasons for the recommendation",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "threats": {
            "description": "List of all detected threats",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "transaction_data": {
            "$ref": "#/components/schemas/TransactionDataDto"
          },
          "custom_attributes": {
            "type": "object",
            "description": "Custom attributes as a dictionary"
          },
          "triggered_rules": {
            "type": "array",
            "description": "Names of the rules that were triggered for this action. Empty when no rule was triggered.\n",
            "items": {
              "type": "string"
            },
            "example": [
              "Block restricted jurisdictions",
              "Challenge new device"
            ]
          }
        },
        "required": [
          "id",
          "issued_at",
          "recommendation",
          "risk_score",
          "context",
          "reasons",
          "threats"
        ]
      },
      "PayerDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Payer/Payee name",
            "example": "John Doe",
            "minLength": 1,
            "maxLength": 100
          },
          "bankIdentifier": {
            "type": "string",
            "description": "Bank identifier",
            "example": "CHASEUS33",
            "minLength": 1,
            "maxLength": 40
          },
          "branchIdentifier": {
            "type": "string",
            "description": "Branch identifier",
            "example": "123456",
            "minLength": 1,
            "maxLength": 40
          },
          "accountNumber": {
            "type": "string",
            "description": "Account number",
            "example": "1234567890123456",
            "minLength": 1,
            "maxLength": 100
          },
          "accountId": {
            "type": "string",
            "description": "Unique identifier for the account",
            "example": "USER_983245",
            "minLength": 1,
            "maxLength": 100
          },
          "accountCountryCode": {
            "type": "string",
            "description": "Country code of the account (ISO-3166-1 alpha-2)",
            "example": "US",
            "minLength": 2,
            "maxLength": 2
          },
          "card": {
            "$ref": "#/components/schemas/CreditCardDto"
          },
          "billingInfo": {
            "$ref": "#/components/schemas/AddressDto"
          },
          "customerTier": {
            "type": "string",
            "description": "Customer tier",
            "example": "premium",
            "minLength": 1,
            "maxLength": 50
          }
        }
      },
      "PayeeDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Payer/Payee name",
            "example": "John Doe",
            "minLength": 1,
            "maxLength": 100
          },
          "bankIdentifier": {
            "type": "string",
            "description": "Bank identifier",
            "example": "CHASEUS33",
            "minLength": 1,
            "maxLength": 40
          },
          "branchIdentifier": {
            "type": "string",
            "description": "Branch identifier",
            "example": "123456",
            "minLength": 1,
            "maxLength": 40
          },
          "accountNumber": {
            "type": "string",
            "description": "Account number",
            "example": "1234567890123456",
            "minLength": 1,
            "maxLength": 100
          },
          "accountId": {
            "type": "string",
            "description": "Unique identifier for the account",
            "example": "USER_983245",
            "minLength": 1,
            "maxLength": 100
          },
          "accountCountryCode": {
            "type": "string",
            "description": "Country code of the account (ISO-3166-1 alpha-2)",
            "example": "US",
            "minLength": 2,
            "maxLength": 2
          },
          "card": {
            "$ref": "#/components/schemas/CreditCardDto"
          }
        }
      },
      "PurchaseDto": {
        "type": "object",
        "properties": {
          "totalItems": {
            "type": "number",
            "description": "Total number of items in the purchase",
            "example": 3
          },
          "products": {
            "description": "List of products in the purchase",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductDto"
            }
          },
          "shippingInfo": {
            "$ref": "#/components/schemas/AddressDto"
          }
        }
      },
      "AvsDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "AVS response code",
            "example": "Y",
            "minLength": 1,
            "maxLength": 10
          },
          "provider": {
            "type": "string",
            "description": "AVS provider name",
            "example": "Stripe",
            "minLength": 1,
            "maxLength": 50
          },
          "matchLevel": {
            "type": "string",
            "description": "AVS match level",
            "enum": [
              "none",
              "postal",
              "street",
              "full",
              "unknown"
            ],
            "example": "full"
          }
        }
      },
      "RecommendationDTO": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Recommendation type",
            "enum": [
              "ALLOW",
              "CHALLENGE",
              "DENY",
              "TRUST"
            ],
            "example": "CHALLENGE"
          },
          "result": {
            "type": "string",
            "description": "The outcome of the action",
            "enum": [
              "success",
              "failure",
              "incomplete"
            ],
            "example": "success"
          },
          "challenge_type": {
            "type": "string",
            "description": "The type of challenge enforced for the reported action",
            "enum": [
              "sms_otp",
              "email_otp",
              "totp",
              "push_otp",
              "voice_otp",
              "idv",
              "captcha",
              "invisible_captcha",
              "password",
              "passkey",
              "document_verification",
              "security_question",
              "knowledge_based_authentication",
              "device_approval",
              "out_of_band",
              "otp",
              "device_biometrics",
              "face_id",
              "fingerprint",
              "mobile_approve",
              "pin",
              "cap_rep_token",
              "symantec_token",
              "duo",
              "secure_id",
              "csm",
              "biometric",
              "devicetag_rep_token",
              "email_verification",
              "magic_link",
              "symantec_pin",
              "web_to_mobile"
            ],
            "example": "email_otp"
          }
        },
        "required": [
          "type"
        ]
      },
      "TransactionRecommendationContextDto": {
        "type": "object",
        "properties": {
          "action_id": {
            "type": "string",
            "description": "Identifier of the client action",
            "example": "885cd06b527a97498200560b67123fe221b5a39fd98d8d22cdb7ca8ec16ed62d"
          },
          "action_type": {
            "type": "string",
            "description": "Type of client action this recommendation was issued for",
            "example": "transaction"
          },
          "action_performed_at": {
            "type": "number",
            "description": "Unix epoch time in milliseconds the action event was reported",
            "example": 1648028118123
          },
          "application_id": {
            "type": "string",
            "description": "Identifies the application associated with the action",
            "example": "ece93f4"
          },
          "tenant_id": {
            "type": "string",
            "description": "Identifies your tenant within Transmit",
            "example": "c2a3d12"
          },
          "client_id": {
            "type": "string",
            "description": "Identifies the client associated with the action",
            "example": "d152ddd.ece93f4.c2a3d12.riskid.security"
          },
          "correlation_id": {
            "type": "string",
            "description": "Any ID that could help relate the action with external context or session (if set via SDK calls)",
            "example": "bcb934d8-89cb-433b-a4c7-b7d94299586b"
          }
        },
        "required": [
          "action_id",
          "action_type",
          "action_performed_at",
          "application_id",
          "tenant_id",
          "client_id"
        ]
      },
      "CreditCardDto": {
        "type": "object",
        "properties": {
          "holderName": {
            "type": "string",
            "description": "Name of the card holder",
            "example": "John Doe",
            "minLength": 1,
            "maxLength": 100
          },
          "bin": {
            "type": "string",
            "description": "Bank Identification Number (first 6 digits of card)",
            "example": "411111",
            "minLength": 6,
            "maxLength": 8
          },
          "last4": {
            "type": "string",
            "description": "Last 4 digits of the credit card number",
            "example": "1234",
            "minLength": 4,
            "maxLength": 4
          }
        }
      },
      "AddressDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Full name",
            "example": "John Doe",
            "minLength": 1,
            "maxLength": 100
          },
          "addressLine1": {
            "type": "string",
            "description": "Address line 1",
            "example": "123 Main St",
            "minLength": 1,
            "maxLength": 255
          },
          "addressLine2": {
            "type": "string",
            "description": "Address line 2",
            "example": "Apt 4B",
            "minLength": 1,
            "maxLength": 255
          },
          "city": {
            "type": "string",
            "description": "City",
            "example": "New York",
            "minLength": 1,
            "maxLength": 100
          },
          "state": {
            "type": "string",
            "description": "State/Province/Region",
            "example": "NY",
            "minLength": 1,
            "maxLength": 100
          },
          "zipPostalCode": {
            "type": "string",
            "description": "ZIP or postal code",
            "example": "10001",
            "minLength": 1,
            "maxLength": 32
          },
          "country": {
            "type": "string",
            "description": "Country code (ISO-3166-1 alpha-2)",
            "example": "US",
            "minLength": 2,
            "maxLength": 2
          },
          "email": {
            "type": "string",
            "description": "Email address",
            "example": "john.doe@example.com",
            "minLength": 3,
            "maxLength": 255
          },
          "phone": {
            "type": "string",
            "description": "Phone number",
            "example": "+1234567890",
            "minLength": 1,
            "maxLength": 32
          }
        }
      },
      "ProductDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the product",
            "example": "PROD_12345",
            "minLength": 1,
            "maxLength": 100
          },
          "name": {
            "type": "string",
            "description": "Name of the product",
            "example": "iPhone 15",
            "minLength": 1,
            "maxLength": 255
          },
          "amount": {
            "type": "number",
            "description": "Amount of the product",
            "example": 1
          },
          "price": {
            "type": "number",
            "description": "Price of the product",
            "example": 999.99
          }
        }
      }
    },
    "securitySchemes": {
      "risk_access_token": {
        "type": "http",
        "scheme": "bearer",
        "description": "An access token generated by the [token endpoint](/openapi/token.openapi/other/getaccesstoken)",
        "bearerFormat": "JWT"
      }
    }
  }
}