Skip to main content

How Evaluations Work

The Evaluation API analyzes dispute data and evidence to provide a confidence assessment that helps you decide whether to submit a dispute to the card scheme.

You submit a dispute to the Evaluation API by specifying its category, the transaction details, and supporting evidences. The API evaluates the strength of the case and returns a confidence score along with any issues 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:

curl -X POST https://api.disputes.play.tripledev.app/api/evaluations/ \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "category": "fraud_online",
  "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"
  },
  "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.play.tripledev.app/api/evaluations/{evaluation_id}/result \
-H "Authorization: Bearer $API_KEY"

Understanding the Result​

The evaluation result contains the confidence level and any failed checks:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "confidence": "high",
  "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

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_online",
        "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_online",
        "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_online", "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 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_online", "dispute", "disputed_amount"],
      "msg": "Input should be greater than 0",
      "type": "greater_than"
    },
    {
      "loc": ["body", "payload", "fraud_online", "evidences", "cardholder_statement"],
      "msg": "String should have at least 35 characters",
      "type": "string_too_short"
    }
  ]
}

Next Steps​