# Evaluate a transaction

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.

Endpoint: POST /transaction-monitoring/evaluate
Security: risk_access_token

## Security:

  - `risk_access_token` (unknown)
    http bearer JWT

## Request fields (application/json):

  - `transaction_data` (object, required)

  - `transaction_data.type` (string)
    Type of transaction
    Enum: "purchase", "bill_payment", "mobile_recharge", "money_transfer", "credit_transfer", "credit_redemption", "top_up", "withdrawal", "investment", "loan", "refund", "other"

  - `transaction_data.method` (string)
    Method used for the transaction
    Enum: "bank_account", "wire", "card", "p2p", "wallet"

  - `transaction_data.reason` (string)
    The reason for the transaction
    Example: Monthly subscription payment

  - `transaction_data.amount` (number)
    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

  - `transaction_data.currency` (string)
    The transaction currency (ISO-4217)
    Example: USD

  - `transaction_data.payer` (object)

  - `transaction_data.payer.name` (string)
    Payer/Payee name
    Example: John Doe

  - `transaction_data.payer.bankIdentifier` (string)
    Bank identifier
    Example: CHASEUS33

  - `transaction_data.payer.branchIdentifier` (string)
    Branch identifier
    Example: 123456

  - `transaction_data.payer.accountNumber` (string)
    Account number
    Example: 1234567890123456

  - `transaction_data.payer.accountId` (string)
    Unique identifier for the account
    Example: USER_983245

  - `transaction_data.payer.accountCountryCode` (string)
    Country code of the account (ISO-3166-1 alpha-2)
    Example: US

  - `transaction_data.payer.card` (object)

  - `transaction_data.payer.card.holderName` (string)
    Name of the card holder
    Example: John Doe

  - `transaction_data.payer.card.bin` (string)
    Bank Identification Number (first 6 digits of card)
    Example: 411111

  - `transaction_data.payer.card.last4` (string)
    Last 4 digits of the credit card number
    Example: 1234

  - `transaction_data.payer.billingInfo` (object)

  - `transaction_data.payer.billingInfo.name` (string)
    Full name
    Example: John Doe

  - `transaction_data.payer.billingInfo.addressLine1` (string)
    Address line 1
    Example: 123 Main St

  - `transaction_data.payer.billingInfo.addressLine2` (string)
    Address line 2
    Example: Apt 4B

  - `transaction_data.payer.billingInfo.city` (string)
    City
    Example: New York

  - `transaction_data.payer.billingInfo.state` (string)
    State/Province/Region
    Example: NY

  - `transaction_data.payer.billingInfo.zipPostalCode` (string)
    ZIP or postal code
    Example: 10001

  - `transaction_data.payer.billingInfo.country` (string)
    Country code (ISO-3166-1 alpha-2)
    Example: US

  - `transaction_data.payer.billingInfo.email` (string)
    Email address
    Example: john.doe@example.com

  - `transaction_data.payer.billingInfo.phone` (string)
    Phone number
    Example: +1234567890

  - `transaction_data.payer.customerTier` (string)
    Customer tier
    Example: premium

  - `transaction_data.payee` (object)

  - `transaction_data.payee.name` (string)
    Payer/Payee name
    Example: John Doe

  - `transaction_data.payee.bankIdentifier` (string)
    Bank identifier
    Example: CHASEUS33

  - `transaction_data.payee.branchIdentifier` (string)
    Branch identifier
    Example: 123456

  - `transaction_data.payee.accountNumber` (string)
    Account number
    Example: 1234567890123456

  - `transaction_data.payee.accountId` (string)
    Unique identifier for the account
    Example: USER_983245

  - `transaction_data.payee.accountCountryCode` (string)
    Country code of the account (ISO-3166-1 alpha-2)
    Example: US

  - `transaction_data.channelId` (string)
    Identifier for the channel used for the transaction
    Example: MOBILE_APP

  - `transaction_data.transactionDate` (number)
    The transaction timestamp (Unix epoch in milliseconds or seconds). Must be a non-negative integer.
    Example: 1712594340000

  - `transaction_data.purchase` (object)

  - `transaction_data.purchase.totalItems` (number)
    Total number of items in the purchase
    Example: 3

  - `transaction_data.purchase.products` (array)
    List of products in the purchase

  - `transaction_data.purchase.products.id` (string)
    Unique identifier for the product
    Example: PROD_12345

  - `transaction_data.purchase.products.name` (string)
    Name of the product
    Example: iPhone 15

  - `transaction_data.purchase.products.amount` (number)
    Amount of the product
    Example: 1

  - `transaction_data.purchase.products.price` (number)
    Price of the product
    Example: 999.99

  - `transaction_data.avs` (object)

  - `transaction_data.avs.code` (string)
    AVS response code
    Example: Y

  - `transaction_data.avs.provider` (string)
    AVS provider name
    Example: Stripe

  - `transaction_data.avs.matchLevel` (string)
    AVS match level
    Enum: "none", "postal", "street", "full", "unknown"

  - `custom_attributes` (object)
    Custom attributes add context to an action but must match the schema defined in the Portal. Invalid attributes are ignored.

  - `correlation_id` (string)
    Any ID that could help relate the action with external context or session
    Example: 550e8400-e29b-41d4-a716-446655440000

## Response 200:

  - `200` (unknown)
    Transaction evaluated successfully

## Response 200 fields (application/json):

  - `action_token` (string, required)
    The token returned when the transaction event was reported.
    Example: ea49707f023f48d64a7a817a2e7a5ff4277281a8f8ac1848ccac407967d9d2ce

  - `recommendation` (object, required)

  - `recommendation.id` (string, required)
    Recommendation identifier

  - `recommendation.issued_at` (number, required)
    Unix epoch time in milliseconds this recommendation was issued at

  - `recommendation.recommendation` (object, required)

  - `recommendation.recommendation.type` (string, required)
    Recommendation type
    Enum: "ALLOW", "CHALLENGE", "DENY", "TRUST"

  - `recommendation.recommendation.result` (string)
    The outcome of the action
    Enum: "success", "failure", "incomplete"

  - `recommendation.recommendation.challenge_type` (string)
    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"

  - `recommendation.risk_score` (number, required)
    Used to assess the risk level of the client action

  - `recommendation.context` (object, required)

  - `recommendation.context.action_id` (string, required)
    Identifier of the client action
    Example: 885cd06b527a97498200560b67123fe221b5a39fd98d8d22cdb7ca8ec16ed62d

  - `recommendation.context.action_type` (string, required)
    Type of client action this recommendation was issued for
    Example: transaction

  - `recommendation.context.action_performed_at` (number, required)
    Unix epoch time in milliseconds the action event was reported
    Example: 1648028118123

  - `recommendation.context.application_id` (string, required)
    Identifies the application associated with the action
    Example: ece93f4

  - `recommendation.context.tenant_id` (string, required)
    Identifies your tenant within Transmit
    Example: c2a3d12

  - `recommendation.context.client_id` (string, required)
    Identifies the client associated with the action
    Example: d152ddd.ece93f4.c2a3d12.riskid.security

  - `recommendation.context.correlation_id` (string)
    Any ID that could help relate the action with external context or session (if set via SDK calls)
    Example: bcb934d8-89cb-433b-a4c7-b7d94299586b

  - `recommendation.reasons` (array, required)
    Explains the reasons for the recommendation

  - `recommendation.threats` (array, required)
    List of all detected threats

  - `recommendation.transaction_data` (object)

  - `recommendation.transaction_data.type` (string)
    Type of transaction
    Enum: "purchase", "bill_payment", "mobile_recharge", "money_transfer", "credit_transfer", "credit_redemption", "top_up", "withdrawal", "investment", "loan", "refund", "other"

  - `recommendation.transaction_data.method` (string)
    Method used for the transaction
    Enum: "bank_account", "wire", "card", "p2p", "wallet"

  - `recommendation.transaction_data.reason` (string)
    The reason for the transaction
    Example: Monthly subscription payment

  - `recommendation.transaction_data.amount` (number)
    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

  - `recommendation.transaction_data.currency` (string)
    The transaction currency (ISO-4217)
    Example: USD

  - `recommendation.transaction_data.payer` (object)

  - `recommendation.transaction_data.payer.name` (string)
    Payer/Payee name
    Example: John Doe

  - `recommendation.transaction_data.payer.bankIdentifier` (string)
    Bank identifier
    Example: CHASEUS33

  - `recommendation.transaction_data.payer.branchIdentifier` (string)
    Branch identifier
    Example: 123456

  - `recommendation.transaction_data.payer.accountNumber` (string)
    Account number
    Example: 1234567890123456

  - `recommendation.transaction_data.payer.accountId` (string)
    Unique identifier for the account
    Example: USER_983245

  - `recommendation.transaction_data.payer.accountCountryCode` (string)
    Country code of the account (ISO-3166-1 alpha-2)
    Example: US

  - `recommendation.transaction_data.payer.card` (object)

  - `recommendation.transaction_data.payer.card.holderName` (string)
    Name of the card holder
    Example: John Doe

  - `recommendation.transaction_data.payer.card.bin` (string)
    Bank Identification Number (first 6 digits of card)
    Example: 411111

  - `recommendation.transaction_data.payer.card.last4` (string)
    Last 4 digits of the credit card number
    Example: 1234

  - `recommendation.transaction_data.payer.billingInfo` (object)

  - `recommendation.transaction_data.payer.billingInfo.name` (string)
    Full name
    Example: John Doe

  - `recommendation.transaction_data.payer.billingInfo.addressLine1` (string)
    Address line 1
    Example: 123 Main St

  - `recommendation.transaction_data.payer.billingInfo.addressLine2` (string)
    Address line 2
    Example: Apt 4B

  - `recommendation.transaction_data.payer.billingInfo.city` (string)
    City
    Example: New York

  - `recommendation.transaction_data.payer.billingInfo.state` (string)
    State/Province/Region
    Example: NY

  - `recommendation.transaction_data.payer.billingInfo.zipPostalCode` (string)
    ZIP or postal code
    Example: 10001

  - `recommendation.transaction_data.payer.billingInfo.country` (string)
    Country code (ISO-3166-1 alpha-2)
    Example: US

  - `recommendation.transaction_data.payer.billingInfo.email` (string)
    Email address
    Example: john.doe@example.com

  - `recommendation.transaction_data.payer.billingInfo.phone` (string)
    Phone number
    Example: +1234567890

  - `recommendation.transaction_data.payer.customerTier` (string)
    Customer tier
    Example: premium

  - `recommendation.transaction_data.payee` (object)

  - `recommendation.transaction_data.payee.name` (string)
    Payer/Payee name
    Example: John Doe

  - `recommendation.transaction_data.payee.bankIdentifier` (string)
    Bank identifier
    Example: CHASEUS33

  - `recommendation.transaction_data.payee.branchIdentifier` (string)
    Branch identifier
    Example: 123456

  - `recommendation.transaction_data.payee.accountNumber` (string)
    Account number
    Example: 1234567890123456

  - `recommendation.transaction_data.payee.accountId` (string)
    Unique identifier for the account
    Example: USER_983245

  - `recommendation.transaction_data.payee.accountCountryCode` (string)
    Country code of the account (ISO-3166-1 alpha-2)
    Example: US

  - `recommendation.transaction_data.channelId` (string)
    Identifier for the channel used for the transaction
    Example: MOBILE_APP

  - `recommendation.transaction_data.transactionDate` (number)
    The transaction timestamp (Unix epoch in milliseconds or seconds). Must be a non-negative integer.
    Example: 1712594340000

  - `recommendation.transaction_data.purchase` (object)

  - `recommendation.transaction_data.purchase.totalItems` (number)
    Total number of items in the purchase
    Example: 3

  - `recommendation.transaction_data.purchase.products` (array)
    List of products in the purchase

  - `recommendation.transaction_data.purchase.products.id` (string)
    Unique identifier for the product
    Example: PROD_12345

  - `recommendation.transaction_data.purchase.products.name` (string)
    Name of the product
    Example: iPhone 15

  - `recommendation.transaction_data.purchase.products.amount` (number)
    Amount of the product
    Example: 1

  - `recommendation.transaction_data.purchase.products.price` (number)
    Price of the product
    Example: 999.99

  - `recommendation.transaction_data.avs` (object)

  - `recommendation.transaction_data.avs.code` (string)
    AVS response code
    Example: Y

  - `recommendation.transaction_data.avs.provider` (string)
    AVS provider name
    Example: Stripe

  - `recommendation.transaction_data.avs.matchLevel` (string)
    AVS match level
    Enum: "none", "postal", "street", "full", "unknown"

  - `recommendation.custom_attributes` (object)
    Custom attributes as a dictionary

## Response 400:

  - `400` (unknown)
    Bad request

## Response 400 fields (application/json):

  - `statusCode` (number, required)

  - `error` (string, required)

  - `message` (object, required)

## Response 401:

  - `401` (unknown)
    Invalid authentication

## Response 401 fields (application/json):

  - `statusCode` (number, required)

  - `error` (string, required)

  - `message` (object, required)

## Response 403:

  - `403` (unknown)
    Invalid authorization

## Response 403 fields (application/json):

  - `statusCode` (number, required)

  - `error` (string, required)

  - `message` (object, required)

## Response 429:

  - `429` (unknown)
    Rate limit reached

## Response 429 fields (application/json):

  - `statusCode` (number, required)

  - `error` (string, required)

  - `message` (object, required)

## Response 500:

  - `500` (unknown)
    Internal error

## Response 500 fields (application/json):

  - `statusCode` (number, required)

  - `error` (string, required)

  - `message` (object, required)