Evaluation Payload

An evaluation request is composed of five required parts:

Field	Description
`category`	The high-level type of dispute being evaluated
`dispute`	The disputed amount and currency
`transaction`	Details of the original transaction
`card`	Masked PAN (the first 6 and last 4 digits)
`evidences`	Supporting evidence (varies by category)

Category	Description
`cancelled`	Cancellation disputes where the cardholder claims policy mismatch, retained fees, or unresolved cancellation loss
`fraud`	Unauthorized transactions
`service_not_received`	Goods or services paid for but not delivered
`processing_duplicate`	Transaction charged multiple times

Dispute

The dispute object specifies the amount and currency being disputed. This may match the full transaction amount or be a partial amount when only some items or services are being disputed.

Required Dispute Fields

Field	Type	Description
`disputed_amount`	decimal	The amount being disputed, in major currency units (e.g., dollars, not cents). This may match the full transaction amount or be a partial amount when only some items or services are being disputed.
`disputed_currency`	string	The ISO 4217 three-letter currency code for the disputed amount (e.g., 'USD', 'EUR', 'GBP'). (3 characters)

Transaction

The transaction object contains details of the original charge being disputed.

Required Transaction Fields

Field	Type	Description
`transaction_id`	string	Your unique identifier for this transaction. Used to correlate the dispute with your internal records.
`card_scheme`	string	Card network that processed the transaction. Options: VISA (Visa network), MC (Mastercard network). Each network has different dispute rules and timeframes.
`channel_type`	string	Channel where the transaction occurred. Options: ECOMMERCE (online/card-not-present purchase), POS (in-person card-present purchase), ATM (cash withdrawal at ATM).
`merchant_name`	string	Merchant name exactly as it appears on the cardholder's statement. This is how the cardholder identifies the charge.
`merchant_country`	string	ISO 3166-1 alpha-3 country code where the merchant is located (e.g., 'USA', 'GBR', 'DEU'). (3 characters)
`transaction_amount`	decimal	Transaction amount in major currency units (e.g., dollars, not cents). This is the full amount that was charged to the card.
`transaction_currency`	string	Three-letter ISO 4217 currency code for the transaction amount (e.g., USD, EUR, GBP). (3 characters)
`merchant_id`	string	Unique identifier assigned to the merchant by the acquirer. Used to identify the business across multiple transactions and terminals.
`transaction_timestamp`	date	Date and time when the transaction was authorized, in ISO 8601 format (UTC). This is when the cardholder initiated the purchase.
`merchant_category_code`	string	Merchant Category Code (MCC). A four-digit code classifying the merchant's business type (e.g., 5411 for grocery stores, 5812 for restaurants).
`arn`	string	Acquirer Reference Number. A unique 23-digit identifier assigned by the acquirer to trace the transaction through the card network.

Optional Transaction Fields

Field	Type	Description
`settlement_timestamp`	date	Date and time when the transaction was settled, in ISO 8601 format (UTC). Settlement occurs when funds are transferred from issuer to acquirer.
`rrn`	string	Retrieval Reference Number. A 12-digit identifier used to locate and retrieve the original transaction record.
`batch_id`	string	Batch identifier from the acquirer. Transactions are grouped into batches for settlement processing, typically at end of business day.
`terminal_id`	string	Identifier of the payment terminal or point-of-sale device where the transaction was processed. Useful for card-present transactions.
`device_fingerprint`	string	A unique identifier derived from the device used to initiate the transaction (e.g., browser fingerprint, device ID). Used to match transactions originating from the same device.
`device_location`	string	IP address of the device at transaction time, if available
`avs_result`	string	Address Verification Service result. Compares only numeric portions of the billing address (house number and ZIP code) against the issuer's records. Options include MATCH, NO_MATCH, PARTIAL_MATCH, and NOT_PROVIDED.
`cvv_match`	boolean	Whether the CVV2/CVC2 (3-4 digit security code on the card) matched during the transaction.
`eci_code`	string	The final Electronic Commerce Indicator (ECI) code for the transaction. Indicates the level of authentication achieved (e.g., '05' for fully authenticated 3DS on Visa, '02' for Mastercard).
`pos_entry_type`	string	How card data was captured at POS. Options include MANUAL, CHIP, CONTACTLESS, MAGSTRIPE, FALLBACK, and UNKNOWN.
`terminal_entry_capability`	string	Terminal-supported entry methods. Options include MSR_ONLY, MSR_MANUAL, MANUAL_ONLY, CHIP, CONTACTLESS_CHIP_ONLY, MSR_CHIP, MSR_CONTACTLESS, CHIP_CONTACTLESS, MSR_CHIP_CONTACTLESS, and UNKNOWN.
`authorization_mode`	string	How authorization was performed. ONLINE means issuer/network auth; OFFLINE means EMV offline path; NO_AUTH indicates no authorization step; UNKNOWN means the authorization path is unavailable or could not be mapped.
`is_network_tokenized`	boolean	Whether the disputed transaction was processed using a network token (for example, wallet/device tokenization) instead of only PAN details.

Card

The card object contains the card snapshot used to evaluate the dispute, including the card identifiers and chip/PIN capabilities relevant to the transaction.

Required Card Fields

Field	Type	Description
`bin`	string	Card BIN (Issuer Identification Number), 6 to 8 digits. Use the identifier associated with the card details used in this transaction. (min 6 characters)
`last_4`	string	Last 4 digits associated with the card details used in this transaction. For network-tokenized payments, these may correspond to tokenized card details. (4 characters)

Optional Card Fields

Field	Type	Description
`emv_chip_enabled`	boolean	Whether the card profile supports EMV chip functionality for in-person payments.
`emv_pin_preferring`	boolean	Whether the card is configured to prefer PIN verification in EMV chip flows.

Evidences

The evidences object contains supporting information for the dispute. The required and optional fields depend on the selected category.

Evidence by Category

Select a category below to view its evidence requirements and example request:

Select Dispute Category:

Cancelled

Evidence required for cancellation disputes. These disputes occur when a cardholder recognizes the transaction but claims cancellation handling or resulting charges were inconsistent with policy/disclosure.

*Required Evidences2

cardholder_statementstringRequired

A written statement from the cardholder describing the cancellation claim, including what was purchased/cancelled and why the charged amount is disputed. (min 35 characters)

purchase_typestringRequired

Type of purchase. Options: product (goods) or service (bookings/subscriptions).

Optional Evidences2

cancelled_atdate

Date when the cardholder requested cancellation from the merchant (YYYY-MM-DD).

additional_documentationarray

Optional list of uploaded file IDs for the `additional_documentation` evidence field (for example purchase receipts, cancellation policy terms, disclosure documents, shipment status proofs, or return attempt evidence). Maximum 5 files.

Example Request

{
  "category": "cancelled",
  "dispute": {
    "disputed_amount": 149.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": "mid_123",
    "transaction_timestamp": "2024-01-20T00:00:00Z",
    "settlement_timestamp": "2024-01-22T00:00:00Z",
    "merchant_category_code": "5311",
    "arn": "12345678901234567890123",
    "rrn": "123456789012",
    "batch_id": "batch_001",
    "terminal_id": "term_01",
    "device_fingerprint": "dfp_abc123xyz",
    "device_location": "203.0.113.42",
    "avs_result": "MATCH",
    "cvv_match": true,
    "eci_code": "05",
    "pos_entry_type": "CHIP",
    "terminal_entry_capability": "MSR_CHIP_CONTACTLESS",
    "authorization_mode": "ONLINE",
    "is_network_tokenized": true
  },
  "evidences": {
    "cardholder_statement": "I cancelled the booking in time but was charged a fee that does not match policy.",
    "purchase_type": "service"
  }
}

Required vs Optional Evidence

Required evidence must be provided for the evaluation to proceed. Missing required evidence will result in a validation error.
Optional evidence enhances the evaluation. Providing more evidence generally leads to better confidence outcomes and fewer unresolved gaps.

tip

Even if evidence is optional, providing it can significantly improve your confidence level. The more context you provide, the better the evaluation and the scheme-facing output.

Cardholder Statement

The cardholder_statement is required for all categories. This is the cardholder's description of why they are disputing the transaction.

Requirements:

Minimum 35 characters
Should clearly describe the dispute from the cardholder's perspective
Should include relevant details about why the transaction is being disputed

Example:

I recognize this purchase, requested cancellation through the merchant channel, and the cancellation charge does not match the policy shown at checkout. I did not receive any refund, voucher, or credit, and the cancelled service portion was not used.

Additional Documentation

Some categories accept uploaded supporting documents through the additional_documentation evidence field. Upload each file first, then reference the returned file IDs in the additional_documentation array of your evaluation request.

Upload Endpoint

curl -X POST https://api.disputes.sandbox.tripledev.app/api/files/evidence_files/ \
-H "Authorization: Bearer $API_KEY" \
-F "file=@police_report.pdf"

The response contains the file metadata:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://files.example.com/evidence/550e8400-e29b-41d4-a716-446655440000",
  "original_name": "police_report.pdf",
  "mime_type": "application/pdf",
  "size": 245678
}

Then use the returned file IDs in evidences.additional_documentation:

{
  "evidences": {
    "additional_documentation": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }
}

You can include up to 5 uploaded file IDs in additional_documentation. Use this field for supporting material such as receipts, merchant communications, policy documents, police reports, or other documents relevant to the dispute.

Supported File Types

Type	Extensions	Max Size
PDF	`.pdf`	10 MB
Images	`.jpg`, `.jpeg`, `.png`	10 MB

The API returns a 422 status code when file validation fails (unsupported MIME type, empty file, or file too large).

Category​

Dispute​

Required Dispute Fields

Transaction​

Required Transaction Fields

Optional Transaction Fields

Card​

Required Card Fields

Optional Card Fields

Evidences​

Evidence by Category​

Cancelled

*Required Evidences2

Optional Evidences2

Example Request

Required vs Optional Evidence​

Cardholder Statement​

Additional Documentation​

Upload Endpoint​

Supported File Types​

Category