Skip to main content

How Evaluations Work

The Evaluation API analyzes dispute data and evidence to produce a confidence assessment, propose a reason code, and surface any issues that may weaken the case before you submit it to the card scheme.

You submit a dispute to the Evaluation API by specifying its high-level category, the transaction details, and supporting evidences. The API evaluates the strength of the case and returns a confidence score, a proposed reason code if available, and any issues or missing information that may weaken it.

Evaluation Flow​

When you submit a dispute for evaluation, the API returns an evaluation ID immediately. The evaluation is then processed asynchronously and once it finishes, the result is available to retrieve. The recommended way to know when a result is ready is by configuring a webhook.

Evaluation Flow

1. Submit a Dispute for Evaluation​

Send a POST request with your dispute data. The request structure varies by category, but the category itself stays high-level. For example, fraud disputes are submitted as fraud, and the evaluation uses the full case context to determine the final scheme reason code:

curl -X POST https://api.disputes.sandbox.tripledev.app/api/evaluations/ \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "category": "fraud",
  "dispute": {
    "disputed_amount": 299.99,
    "disputed_currency": "USD"
  },
  "transaction": {
    "transaction_id": "txn_12345",
    "card_scheme": "MC",
    "channel_type": "ECOMMERCE",
    "merchant_name": "ACME Store",
    "merchant_country": "USA",
    "transaction_amount": 299.99,
    "transaction_currency": "USD",
    "merchant_id": "MERCHANT123",
    "transaction_timestamp": "2024-01-20T10:30:00Z",
    "settlement_timestamp": "2024-01-22T00:00:00Z",
    "arn": "12345678901234567890123",
    "rrn": "123456789012",
    "merchant_category_code": "5311",
    "terminal_id": "term_01",
    "mobile_wallet": null,
    "avs_result": "NO_MATCH",
    "cvv_match": false,
    "eci_code": "05",
    "batch_id": "batch_001"
  },
  "card": {
    "bin": "54133388",
    "last_4": "1234",
    "emv_chip_enabled": true,
    "emv_pin_preferring": false
  },
  "evidences": {
    "cardholder_statement": "I did not make this purchase. My card details were stolen..."
  }
}'

2. Store the Evaluation ID​

The API immediately returns an evaluation ID. You must store this ID to retrieve the result later.

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
Important

The evaluation process is asynchronous. Store the id value, you will need it to retrieve the evaluation result.

3. Receive the Evaluation Result​

Once processing is complete, you can receive the result in two ways:

Configure a webhook endpoint to receive results automatically as soon as the evaluation is ready. This is the recommended approach for production integrations.

See Webhooks Guide for setup instructions.

Fallback: Polling​

If you cannot use webhooks, you can poll the result endpoint using the evaluation ID. Since evaluations are processed asynchronously, you will need to define a polling strategy to periodically check for results. Webhooks avoid this by delivering results to your server as soon as they are ready.

curl https://api.disputes.sandbox.tripledev.app/api/evaluations/{evaluation_id}/result \
-H "Authorization: Bearer $API_KEY"

Understanding the Result​

The evaluation result contains the confidence level, the proposed reason code, and any failed checks:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "confidence": "high",
  "reason_code": "4837",
  "failed_checks": []
}

Confidence​

The confidence level indicates the strength of the dispute case:

LevelDescription
highStrong case with sufficient evidence
moderate_highGood case, minor improvements possible
moderate_lowModerate case, may benefit from additional evidence
lowWeak case, significant issues identified

Reason Code​

We return reason_code when the system is able to classify the dispute precisely enough to determine a scheme-facing reason code. If the available information is not sufficient for a precise classification, reason_code is null and the failed checks will highlight the additional information needed.

Failed Checks​

The failed_checks array uses a format similar to Pydantic validation errors. Each entry identifies a specific issue:

{
  "id": "6c825d27-db81-4f60-8f7c-2d87ac0b71a1",
  "confidence": "low",
  "failed_checks": [
    {
      "loc": [
        "body",
        "payload",
        "fraud",
        "evidences",
        "cardholder_statement"
      ],
      "msg": "No meaningful purchase details were provided. Without basic context, the dispute shouldn't be raised.",
      "type": "error"
    },
    {
      "loc": [
        "body",
        "payload",
        "fraud",
        "evidences",
        "expected_at"
      ],
      "msg": "The expected delivery or service date has not yet passed. The merchant may still be within their fulfilment window.",
      "type": "error"
    }
  ]
}

Each failed check contains:

FieldDescription
locPath to the field (e.g., ["body", "payload", "fraud", "evidences", "cardholder_statement"])
msgDescription of the issue
typeEither error (validation issue) or missing_info (recommended evidence)

Use failed checks to understand why a dispute received a lower confidence score, what additional information is missing, and what might improve it.

Validation Errors​

If your request has validation issues, the API returns a 422 response with Pydantic-style errors:

{
  "detail": [
    {
      "loc": ["body", "payload", "fraud", "dispute", "disputed_amount"],
      "msg": "Input should be greater than 0",
      "type": "greater_than"
    },
    {
      "loc": ["body", "payload", "fraud", "evidences", "cardholder_statement"],
      "msg": "String should have at least 35 characters",
      "type": "string_too_short"
    }
  ]
}

Next Steps​