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)
`description`	string	A written statement from the cardholder describing the dispute in their own words. (min 35 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. (min 1 characters)
`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. (min 1 characters)
`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. (min 1 characters)
`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). (4 characters)
`arn`	string	Acquirer Reference Number. A unique 23-digit identifier assigned by the acquirer to trace the transaction through the card network. (min 1 characters)
`card_scheme`	string	Card network that processed the transaction. Options: VISA (Visa network), MC (Mastercard network). Each network has different dispute rules and timeframes.

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.
`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, 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.
`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_bin`	string	Card BIN (Issuer Identification Number), 6 to 8 digits. Use the identifier associated with the card details used in this transaction.
`card_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.
`card_token`	string	Card Token
`card_emv_chip_enabled`	boolean	Whether the card profile supports EMV chip functionality for in-person payments.
`card_emv_pin_preferring`	boolean	Whether the card is configured to prefer PIN verification in EMV chip flows.

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.

No card fields available.

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:

!No evidence data available

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 do not recognize this merchant or transaction. I did not authorize this purchase, did not place the order, and did not share my card details with anyone. My card was in my possession at the time.

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.play.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​

Evidences​

Evidence by Category​

Required vs Optional Evidence​

Cardholder Statement​

Additional Documentation​

Upload Endpoint​

Supported File Types​

Category