Threedsmax Custom Transaction Rules: Build, Deploy, and Test Your 3DS2 Risk Logic

Why Custom Rules Matter

When a merchant uses Threedsmax for 3DS2 authentication, the default risk engine applies a set of generic rules that may not match the nuances of a particular business. Custom transaction rules let you define dynamic, fine‑grained logic that can Accept, Challenge, or Decline transactions based on any attribute the platform exposes – amount, currency, device fingerprint, or even a merchant‑specific tag.

Building a Rule Set

Rules are defined in JSON and managed through the Threedsmax API. Each rule contains a condition and an action. The engine evaluates rules sequentially; the first rule that matches stops evaluation, so ordering is critical.

Rule Structure

Field	Type	Description
id	string	Unique identifier used by your backend to reference the rule.
description	string	Human‑readable note.
condition	object	Logical expression using operators (AND, OR, NOT, ==, !=, >, <, >=, <=).
action	string	Accept, Challenge, or Decline.
tags	array of string	Optional tags to limit rule application to specific transaction types.

Example JSON Rule Set

The following rule set demonstrates a common use case: Accept low‑value purchases, challenge high‑value ones, and leave mid‑range amounts for issuer decision. The rules are applied only to "one‑off" purchases.

{
  "rules": [
    {
      "id": "low_value_accept",
      "description": "Accept transactions below $50.",
      "condition": {
        "AND": [
          { "amount": { "lt": 50 } },
          { "currency": { "eq": "USD" } },
          { "transaction_type": { "eq": "one_off" } }
        ]
      },
      "action": "Accept",
      "tags": ["one_off"]
    },
    {
      "id": "high_value_challenge",
      "description": "Challenge transactions above $100.",
      "condition": {
        "AND": [
          { "amount": { "gt": 100 } },
          { "currency": { "eq": "USD" } },
          { "transaction_type": { "eq": "one_off" } }
        ]
      },
      "action": "Challenge",
      "tags": ["one_off"]
    }
  ]
}

Deploying the Rule Set

Use the Threedsmax REST API to upload the JSON file. The following curl command runs on the machine that hosts your integration. Replace {API_KEY} with your secret key and {BASE_URL} with the sandbox or production endpoint.

curl -X POST \
  "{BASE_URL}/api/v1/rulesets" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d @ruleset.json

After the request succeeds, the new rules become active within approximately five minutes. Use the console to confirm the rule set appears in the "Custom Rules" section.

Testing in Sandbox

1. Create a test transaction with amount: 30 and verify the response status is Accept.
2. Create another transaction with amount: 70 and confirm the system defers to issuer decision (no explicit Accept or Challenge).
3. Finally, test amount: 150 and expect a Challenge response.
4. Check the Rule Evaluation Log in the Threedsmax console to see which rule matched and why.

Limits and Common Pitfalls

• Rule Ordering: Placing a broad Accept rule before a specific Challenge rule can bypass fraud checks. Always review the sequence in the console.
• Wildcard & Regex: Patterns that match too broadly can flag legitimate high‑value purchases. Test with a range of values before going live.
• Sandbox Validation: Rules that work in sandbox may behave differently in production due to issuer‑specific logic. Run parallel tests in both environments.
• Conversion Impact: Over‑aggressive Challenge rules can hurt checkout flow. Use analytics to monitor drop‑off rates after rule deployment.
• Deterministic Logic: Functions that return random values (e.g., rand()) lead to inconsistent outcomes. Keep conditions pure and side‑effect free.
• Performance: Complex nested conditions can add latency. Profile the rule set; if response times exceed 200 ms, simplify the logic or split into multiple rule sets.

Wrapping Up

Custom transaction rules give merchants precise control over 3DS2 flows. By following the JSON schema, deploying via the API, and rigorously testing in sandbox, you can align the authentication experience with your risk appetite and business model while keeping latency low and conversion high.