# Create a case Source: https://docs.decisionly.com/api-reference/v2-cases/create-a-case /api-reference/v2/openapi.yaml post /v2/issuer/cases Creates a new case. # Delete a case Source: https://docs.decisionly.com/api-reference/v2-cases/delete-a-case /api-reference/v2/openapi.yaml delete /v2/issuer/cases/{case_id} Deletes a case by ID. Filed cases cannot be deleted. # File a case Source: https://docs.decisionly.com/api-reference/v2-cases/file-a-case /api-reference/v2/openapi.yaml post /v2/issuer/cases/{case_id}/file Files a case with the card network. The case must be in 'created' status to be filed. # List all cases Source: https://docs.decisionly.com/api-reference/v2-cases/list-all-cases /api-reference/v2/openapi.yaml get /v2/issuer/cases Returns a list of all cases. # Retrieve a case Source: https://docs.decisionly.com/api-reference/v2-cases/retrieve-a-case /api-reference/v2/openapi.yaml get /v2/issuer/cases/{case_id} Returns a case by ID. # Update a case Source: https://docs.decisionly.com/api-reference/v2-cases/update-a-case /api-reference/v2/openapi.yaml put /v2/issuer/cases/{case_id} Updates a case. Filed cases cannot be updated. Partial updates are supported - you only need to include the fields you want to update in the request body. # Withdraw a case Source: https://docs.decisionly.com/api-reference/v2-cases/withdraw-a-case /api-reference/v2/openapi.yaml post /v2/issuer/cases/{case_id}/withdraw Withdraws a case. The case must be in 'created' or 'chargeback_filed' status to be withdrawn. # Create a claim Source: https://docs.decisionly.com/api-reference/v2-claims/create-a-claim /api-reference/v2/openapi.yaml post /v2/issuer/claims Creates a new claim by grouping existing cases together. # Create a claim with cases Source: https://docs.decisionly.com/api-reference/v2-claims/create-a-claim-with-cases /api-reference/v2/openapi.yaml post /v2/issuer/new_claim Creates a new claim and all its cases in a single request. # File a claim Source: https://docs.decisionly.com/api-reference/v2-claims/file-a-claim /api-reference/v2/openapi.yaml post /v2/issuer/claims/{claim_id}/file Files each case in the claim to the card network. # List all claims Source: https://docs.decisionly.com/api-reference/v2-claims/list-all-claims /api-reference/v2/openapi.yaml get /v2/issuer/claims Returns a simplified list of all claims. Use the retrieve endpoint to get full claim details with cases. # Retrieve a claim Source: https://docs.decisionly.com/api-reference/v2-claims/retrieve-a-claim /api-reference/v2/openapi.yaml get /v2/issuer/claims/{claim_id} Returns a claim by ID with all associated cases and their full details. # Set claim cases Source: https://docs.decisionly.com/api-reference/v2-claims/set-claim-cases /api-reference/v2/openapi.yaml put /v2/issuer/claims/{claim_id}/cases Replaces all cases in a claim with the supplied list. # Withdraw a claim Source: https://docs.decisionly.com/api-reference/v2-claims/withdraw-a-claim /api-reference/v2/openapi.yaml post /v2/issuer/claims/{claim_id}/withdraw Withdraws all cases in a claim. # List all events Source: https://docs.decisionly.com/api-reference/v2-events/list-all-events /api-reference/v2/openapi.yaml get /v2/issuer/events Returns a list of all events for an account. Events are also delivered via webhooks - see the [Webhooks documentation](/webhooks) for more details. # Upload a file Source: https://docs.decisionly.com/api-reference/v2-files/upload-a-file /api-reference/v2/openapi.yaml post /v2/issuer/files Upload a file that can be attached as documentation to cases. # Authentication Source: https://docs.decisionly.com/authentication Learn how to authenticate with the Decisionly API The Decisionly API uses API keys to authenticate requests. You can view and manage your API keys from your dashboard [settings](https://decisionly.com/settings). ## API Key Prefixes * Test mode secret keys have the prefix `test_` * Live mode secret keys have the prefix `live_` ## HTTP Basic Auth Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password. ```bash cURL theme={null} curl https://api.decisionly.com/v2/issuer/cases \ -u test_d0019b48d05849a6: ``` ```javascript Node.js theme={null} const apiKey = 'test_d0019b48d05849a6'; const auth = Buffer.from(`${apiKey}:`).toString('base64'); fetch('https://api.decisionly.com/v2/issuer/cases', { headers: { 'Authorization': `Basic ${auth}` } }); ``` ```python Python theme={null} import requests api_key = 'test_d0019b48d05849a6' response = requests.get( 'https://api.decisionly.com/v2/issuer/cases', auth=(api_key, '') ) ``` # Case Lifecycle Source: https://docs.decisionly.com/case-lifecycle Understanding case statuses and terminal states A case's `status` field represents its current state in the dispute lifecycle. The status changes as the case progresses through filing, card network interactions, and resolution. For a conceptual overview of each stage, see [What Are Disputes?](/guide#the-dispute-lifecycle). ## Status Values Cases can have the following statuses: ### Active Statuses * `created` - Case has been created but not yet filed * `chargeback_filed` - Chargeback has been filed with the card network * `chargeback_represented` - Merchant has responded with evidence to the chargeback * `prearb_received` - Merchant has challenged the dispute via pre-arbitration (Visa allocation flow) * `prearb_filed` - Pre-arbitration has been filed with the card network * `prearb_rebutted` - Merchant has rebutted the pre-arbitration * `arbitration_filed` - Arbitration has been filed with the card network ### Terminal Statuses Terminal statuses indicate that a case has reached a final state and no further action will be taken: * `won` - Cardholder has won the dispute * `lost` - Cardholder liable for the transaction * `accepted` - Issuer accepted liability * `rejected` - Case was rejected and not filed to the card network * `expired` - Case expired before being filed * `withdrawn` - Case was withdrawn by the cardholder * `merchant_credited` - Merchant issued a refund or credit to the cardholder ## Checking Case Status You can check a case's current status by retrieving it from the API: ```bash theme={null} curl https://api.decisionly.com/v2/issuer/cases/case_abc123 \ -u test_d0019b48d05849a6: ``` The response includes the current status: ```json theme={null} { "case_id": "case_abc123", "status": "chargeback_filed", ... } ``` ## Visa Dispute Flows Visa disputes follow one of two flows depending on the dispute reason: **Allocation flow** (`fraud`, `invalid_authorization`): Visa automatically assigns liability at filing time. There is no representment phase. If the acquirer challenges the dispute, a pre-arbitration is initiated directly (`prearb_received`). The case transitions `chargeback_filed` -> `prearb_received` -> `prearb_filed` (if rebutted) or a terminal status. **Collaboration flow** (all other Visa reason codes): The acquirer responds with evidence, similar to the Mastercard flow. The case goes through `chargeback_represented` before any pre-arbitration. The case transitions `chargeback_filed` -> `chargeback_represented` -> `prearb_filed` (if escalated) -> `prearb_rebutted` -> `arbitration_filed`. ## Status Change Notifications Each status change triggers a corresponding webhook event. See the [Webhooks documentation](/webhooks) for details on subscribing to status change events. # Categorization Source: https://docs.decisionly.com/categorization How Decisionly categorizes disputes with reason 'other' ## Automatic Categorization When you create a case with dispute reason "other", Decisionly first tries to categorize the dispute to one of the standard reasons. If we cannot determine a more specific reason, the dispute remains categorized as "other". # Custom Fields Source: https://docs.decisionly.com/custom-fields Associate additional metadata with your cases Custom fields allow you to associate additional data with your cases using key-value pairs. This feature provides flexibility to include additional information that isn't covered by Decisionly's standard fields. ## Custom Field Requirements Custom fields must adhere to the following requirements: * **Field limit:** Maximum of 25 key-value pairs per case * **Key constraints:** Each key must be 50 characters or fewer * **Value types:** Values must be strings only * **String values:** Maximum length of 250 characters ## Using Custom Fields When creating or updating a case, you can include custom fields in your request body. These fields can be used to: * Store internal reference IDs * Include category or classification data * Trigger workflow rules for automated case handling * Store any other relevant case metadata ## Managing Custom Fields You can create, update, and remove custom fields as needed: * **Create/Update:** Set a value for the field in your request * **Remove:** Set the field value to `null` to completely remove the key-value pair from the case ## Example ```json Creating a case with custom fields theme={null} // POST /v2/issuer/cases { "cardholder": { "issuer_id": "9529456289", "name": "Jane Smith", "email": "jane@example.com", "type": "individual" }, "merchant": { "name": "FoodHub", "category_code": "5812" }, "transaction": { "arn": "48162855246353338636162", "date": "2026-03-01T00:00:00.000Z", "amount": 2990, "currency": "USD", "card": { "network": "mastercard", "type": "credit", "last4": "4242", "expiry_month": 12, "expiry_year": 2028 } }, "dispute": { "amount": 2990, "currency": "USD", "date": "2026-04-01T00:00:00.000Z", "raised_by": "cardholder", "reason": "fraud" }, "custom_fields": { "internal_reference_id": "REF-12345", "wallet_type": "mobile", "customer_category": "platinum", "card_program": "CardHub" } } ``` ```json Updating custom fields theme={null} // PUT /v2/issuer/cases/case_abc123 { "custom_fields": { "internal_reference_id": "REF-67890", "priority": "high" } } ``` ## Custom Fields with Workflow Rules Custom fields can power Decisionly's workflow rules, enabling automated actions based on field values. When using custom fields for workflow automation: * **Maintain consistency:** Use identical string values across cases (e.g., always use "high\_priority" instead of mixing with "High Priority") * **Document conventions:** Maintain internal documentation of your custom field naming and value conventions # Dispute Types Source: https://docs.decisionly.com/dispute-types Understanding dispute categories and required evidence Different types of disputes require different evidence. This page describes what's needed for each dispute type. For network-specific timing rules, see [Filing Timelines](/filing-timelines). For a breakdown of network-specific required fields and documentation, see [Filing Requirements](/filing-requirements). For a high-level overview of fraud vs. merchant disputes, see [What Are Disputes?](/guide#types-of-dispute). ## Available Dispute Types * [`canceled_or_returned`](#canceled-or-returned) - Services canceled or merchandise returned without credit * [`cash_not_received`](#cash-not-received) - ATM/POS funds not dispensed * [`credit_not_processed`](#credit-not-processed) - Refund never received * [`duplicate_charge`](#duplicate-charge) - Charged multiple times * [`fraud`](#fraud) - Cardholder didn't participate in the transaction * [`incorrect_amount`](#incorrect-amount) - Billed an incorrect amount * [`invalid_authorization`](#invalid-authorization) - Merchant didn't have valid authorization * [`other`](#other) - Doesn't fit other categories * [`paid_by_other_means`](#paid-by-other-means) - Paid by other means * [`product_counterfeit`](#product-counterfeit) - Received counterfeit goods * [`product_not_as_described`](#product-not-as-described) - Product was not as described or unacceptable * [`product_not_received`](#product-not-received) - Merchandise never received * [`subscription_canceled`](#subscription-canceled) - Recurring transaction canceled or never agreed to ## Canceled or Returned Use the reason `canceled_or_returned` if the cardholder canceled services or returned merchandise but was not credited. ### Required for Visa * Date received or expected: `issuer_evidence.delivery.date` or `issuer_evidence.delivery.expected_date` * Merchant contact date: `issuer_evidence.merchant_contact.date` ### Recommended Evidence * Details of the resolution attempt with the merchant: * Contact was attempted: `issuer_evidence.merchant_contact.was_attempted` * Contact was successful: `issuer_evidence.merchant_contact.was_successful` * Contact description: `issuer_evidence.merchant_contact.description` * Information about the cancellation or return: * Cancellation ID: `issuer_evidence.cancellation.id` * Cancellation date: `issuer_evidence.cancellation.date` * Cancellation description: `issuer_evidence.cancellation.description` * Return was attempted: `issuer_evidence.return.was_attempted` * Return date: `issuer_evidence.return.date` * Return was successful: `issuer_evidence.return.was_successful` * Return shipping: `issuer_evidence.return.shipping.carrier`, `issuer_evidence.return.shipping.tracking_number` * Return description: `issuer_evidence.return.description` ## Cash Not Received Use the reason `cash_not_received` if some or all of the funds debited from the cardholder's account were not dispensed by an ATM or point of sale terminal. ## Credit Not Processed Use the reason `credit_not_processed` if the cardholder never received a refund. ### Required for Visa * Date of refund promise or credit voucher: `issuer_evidence.refund.promise_date` * A file with category `refund_promise` (credit transaction receipt, voided transaction receipt, or other proof of credit due) ### Recommended Evidence * Details of the resolution attempt with the merchant: * Contact was attempted: `issuer_evidence.merchant_contact.was_attempted` * Contact date: `issuer_evidence.merchant_contact.date` * Contact was successful: `issuer_evidence.merchant_contact.was_successful` * Contact description: `issuer_evidence.merchant_contact.description` * Details of return attempt or cancellation: * Return was attempted: `issuer_evidence.return.was_attempted` * Return date: `issuer_evidence.return.date` * Return was successful: `issuer_evidence.return.was_successful` * Cancellation date: `issuer_evidence.cancellation.date` * Refund details: * Refund was promised: `issuer_evidence.refund.was_promised` * Promise date: `issuer_evidence.refund.promise_date` * Refund description: `issuer_evidence.refund.description` ## Duplicate Charge Use the reason `duplicate_charge` if there was a processing error that charged the cardholder more than once. ### Required for Visa * Prior transaction ARN: `issuer_evidence.prior_transaction.arn` ### Recommended Evidence * Details of the prior, valid transaction: `issuer_evidence.prior_transaction` * Date: `issuer_evidence.prior_transaction.date` * Amount: `issuer_evidence.prior_transaction.amount` * Currency: `issuer_evidence.prior_transaction.currency` ## Fraud Use the reason `fraud` if the cardholder does not recognize the transaction and asserts that they didn't participate in it. Before filing a fraud dispute you must cancel the affected card. ### Required Evidence * Card status: `issuer_evidence.card.is_active` (must be `false`, indicating the card was canceled) * Fraud reporting for network fraud and loss database (at least one must be `true`): * Whether fraud was already reported: `issuer_evidence.fraud.was_reported` * Whether to submit a fraud report when filing: `issuer_evidence.fraud.submit_report` ### Recommended Evidence * Whether the cardholder currently has possession: `issuer_evidence.card.cardholder_has_possession` * The card's possession status at the time of the transaction: `issuer_evidence.card.possession_at_transaction` * The date the card was lost or stolen if applicable: `issuer_evidence.card.lost_date` ## Incorrect Amount Use the reason `incorrect_amount` if the cardholder was billed an incorrect amount. Only the difference between the correct amount and the charged amount can be disputed. ### Required Evidence * Transaction receipt with the correct amount: `issuer_evidence.documentation` (category: `transaction_receipt`) * Correct amount: `issuer_evidence.amount_correction.amount` * Correct currency: `issuer_evidence.amount_correction.currency` ## Invalid Authorization Use the reason `invalid_authorization` if the merchant didn't have a valid authorization for the transaction. *Not* used for fraud cases where the cardholder didn't authorize the transaction. ### Recommended Evidence * Clear description of the transaction and the invalid authorization(s): `issuer_evidence.issuer_explanation` ## Other Use the reason `other` if the dispute reason doesn't fit any of the other categories. ### Required Evidence At least one of the following is required: * Issuer explanation describing why the dispute is being filed: `issuer_evidence.issuer_explanation` * Cardholder explanation with the cardholder's statement about the issue: `issuer_evidence.cardholder_explanation` ## Paid By Other Means Use the reason `paid_by_other_means` if the cardholder made a payment using a method that is different from the disputed transaction. ### Required for Visa * Merchant contact date: `issuer_evidence.merchant_contact.date` ### Required Evidence * Documentation of the alternate payment method (such as a receipt, bill, or bank statement): `issuer_evidence.documentation` (category: `prior_transaction_receipt`) ### Recommended Evidence * Details of the resolution attempt with the merchant: * Contact was attempted: `issuer_evidence.merchant_contact.was_attempted` * Contact was successful: `issuer_evidence.merchant_contact.was_successful` * Contact description: `issuer_evidence.merchant_contact.description` ## Product Counterfeit Use the reason `product_counterfeit` if the cardholder received counterfeit goods that were presented as genuine. ### Required for Visa * Date counterfeit merchandise was received: `issuer_evidence.delivery.date` * A file with category `counterfeit_evidence` (e.g. photo of counterfeit item, third-party verification) ### Recommended Evidence * Details of the resolution attempt with the merchant: * Contact was attempted: `issuer_evidence.merchant_contact.was_attempted` * Contact date: `issuer_evidence.merchant_contact.date` * Contact was successful: `issuer_evidence.merchant_contact.was_successful` * Contact description: `issuer_evidence.merchant_contact.description` * Product type: `issuer_evidence.product.type` * Product description: `issuer_evidence.product.description` * Product condition: `issuer_evidence.product.condition` ## Product Not As Described Use the reason `product_not_as_described` if the product was not as described or unacceptable. ### Required for Visa * Date merchandise/service was received: `issuer_evidence.delivery.date` * Merchant contact date: `issuer_evidence.merchant_contact.date` ### Recommended Evidence * Details of the resolution attempt with the merchant: * Contact was attempted: `issuer_evidence.merchant_contact.was_attempted` * Contact was successful: `issuer_evidence.merchant_contact.was_successful` * Contact description: `issuer_evidence.merchant_contact.description` * Information about return or cancellation: * Return was attempted: `issuer_evidence.return.was_attempted` * Return date: `issuer_evidence.return.date` * Return was successful: `issuer_evidence.return.was_successful` * Return shipping: `issuer_evidence.return.shipping.carrier`, `issuer_evidence.return.shipping.tracking_number` * Cancellation date: `issuer_evidence.cancellation.date` * Cancellation description: `issuer_evidence.cancellation.description` ## Product Not Received Use the reason `product_not_received` if the cardholder never received the merchandise. ### Required for Visa * When the product was expected to be delivered: `issuer_evidence.delivery.expected_date` * Merchant contact date: `issuer_evidence.merchant_contact.date` ### Recommended Evidence * Details of the resolution attempt with the merchant: * Contact was attempted: `issuer_evidence.merchant_contact.was_attempted` * Contact was successful: `issuer_evidence.merchant_contact.was_successful` * Contact description: `issuer_evidence.merchant_contact.description` * Product information (type of good or service): `issuer_evidence.product.type` ## Subscription Canceled Use the reason `subscription_canceled` if the cardholder is disputing a recurring transaction that they either canceled or never agreed to. ### Required for Visa * Cancellation date: `issuer_evidence.cancellation.date` * Merchant contact date: `issuer_evidence.merchant_contact.date` ### Recommended Evidence * Details of the resolution attempt with the merchant: * Contact was attempted: `issuer_evidence.merchant_contact.was_attempted` * Contact was successful: `issuer_evidence.merchant_contact.was_successful` * Contact description: `issuer_evidence.merchant_contact.description` * Details of the cancellation: * Cancellation ID: `issuer_evidence.cancellation.id` * Cancellation date: `issuer_evidence.cancellation.date` * Cancellation description: `issuer_evidence.cancellation.description` ## Standard Information ### Required for All Cases * `cardholder.issuer_id` * `cardholder.name` * `dispute.amount` * `dispute.currency` * `dispute.date` * `dispute.reason` * `merchant.name` * `transaction.amount` * `transaction.arn` * `transaction.card.expiry_month` * `transaction.card.expiry_year` * `transaction.card.last4` * `transaction.card.network` * `transaction.currency` * `transaction.date` ### Recommended for All Cases * `cardholder.email` * `cardholder.type` * `dispute.raised_by` * `issuer_evidence.cardholder_explanation` * `transaction.card.issuer_id` * `transaction.issuer_id` # Errors Source: https://docs.decisionly.com/errors Understanding Decisionly API error responses Decisionly uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed because the request was invalid (missing information, an attempt to file a chargeback after the deadline, etc). Codes in the `5xx` range indicate an error with Decisionly's servers (these are rare). ## HTTP Status Codes Everything worked as expected. A new resource was successfully created. The request was accepted for processing. The request was unacceptable, often due to missing a required argument. Missing or invalid API key. The API key doesn't have permissions to perform the request. The resource or endpoint doesn't exist. Too many requests in a short period of time. Something went wrong on Decisionly's end. # Evidence Review Source: https://docs.decisionly.com/evidence-review Decisionly uses AI to analyze your cases and determine whether they meet the network guidelines for chargebacks. For background on how representment and evidence work, see [What Are Disputes?](/guide#merchant-disputes). ## How Evidence Review Works When you file a non-fraud case, Decisionly performs two types of AI-powered analysis: ### Documentation Review Analyzes uploaded evidence files to determine if they're relevant and valid for the case. Each file is reviewed to check: * Is the document related to the disputed transaction? * Does it support the dispute reason? * Is the document clear and readable? Files marked as invalid don't prevent filing by default, but indicate the evidence may not support the chargeback. ### Conditions Review Analyzes case details and evidence to determine if evidence guidelines are met. The AI checks: * Whether all chargeback conditions are satisfied * Which conditions were detected as met * Which chargeback conditions were not detected This analysis is informational by default and doesn't prevent filing. However, filing a chargeback without meeting evidence guidelines may result in the merchant successfully disputing it. ## Workflow Rules You can configure [workflow rules](/workflow-rules) to control how cases are handled based on AI analysis results. The workflow rules to set up are **Evidence Review Passed** and **Documentation Valid**. **Evidence Review Passed** determines whether a case meets all evidence guidelines for its dispute reason. You could use this rule to **flag for review** when evidence guidelines are not met. **Documentation Valid** determines whether uploaded evidence files are relevant and valid. You could use this rule to **flag for review** when documentation is marked as invalid. ## Dispute Reason Conditions Each dispute reason has specific conditions that should be met to file a valid chargeback with the card network. The AI analyzes your case details and evidence to determine which conditions are satisfied. ### Product Not As Described All of these conditions should be met: * **Merchant Contacted** - The cardholder contacted the merchant, or attempted to contact the merchant, to resolve the dispute * **Merchant Refused Remedy** - The merchant refused to adjust the price, repair, or replace the goods, or issue a credit * **Product Returned** - For physical goods: The cardholder returned the goods or informed the merchant the goods were available for pickup Additionally, **at least one** of these conditions should be met: * **Product Broken** - When delivered, the goods arrived broken or could not be used for the intended purpose * **Product Not As Described** - Goods and services did not conform to their description (wrong color, size, quality, etc.) * **Contract Terms Not Honored** - The merchant did not honor the terms and conditions of the contract, including money back guarantees, written promises, or return policy ### Product Counterfeit All of these conditions should be met: * **Merchant Contacted** - The cardholder contacted the merchant, or attempted to contact the merchant, to resolve the dispute * **Product Counterfeit** - 3rd party verification that the product is counterfeit ### Product Not Received All of these conditions should be met: * **Merchant Contacted** - The cardholder contacted the merchant, or attempted to contact the merchant, to resolve the dispute * **Product Description** - A reasonably specific description of the goods/services purchased is required ### Duplicate Charge The following condition should be met: * **Prior Transaction Details** - Details of the prior transaction providing sufficient details to allow the merchant to locate the prior payment ### Paid By Other Means All of these conditions should be met: * **Prior Transaction Documentation** - Documentation of the alternate payment method (receipt, bill, or bank statement) * **Merchant Contacted** - The cardholder contacted the merchant, or attempted to contact the merchant, to resolve the dispute ### Incorrect Amount The following condition should be met: * **Correct Amount Documentation** - Documentation detailing the correct transaction amount (receipt, final bill, or merchant email confirming price) ### Credit Not Processed The following condition should be met: * **Merchant Contacted** - The cardholder contacted the merchant, or attempted to contact the merchant, to resolve the dispute Additionally, **at least one** of these conditions should be met: * **Refund Not Processed** - The merchant agreed to provide a refund and failed to process that refund * **Partial Credit** - The merchant posted a credit for a reduced amount without proper disclosure ### Subscription Canceled The following condition should be met: * **Merchant Contacted** - The cardholder contacted the merchant, or attempted to contact the merchant, to resolve the dispute Additionally, **at least one** of these conditions should be met: * **Subscription Canceled** - The cardholder notified the merchant to cancel the recurring transaction and the merchant continued to bill the cardholder * **Subscription Not Disclosed** - The transaction was not advertised as recurring ### Canceled or Returned The following condition should be met: * **Merchant Contacted** - The cardholder contacted the merchant, or attempted to contact the merchant, to resolve the dispute Additionally, **at least one** of these conditions should be met: * **Canceled or Returned** - No credit has been issued/processed for the canceled services or merchandise * **Refund Policy Not Disclosed** - The merchant failed to disclose its refund policy at the time of the transaction and is unwilling to accept a return or cancellation * **Timeshare Cancellation Not Processed** - A Timeshare cancellation was not processed within 14 days of the contract or receipt date * **No-Show Fee Charged** - A guaranteed reservation was canceled and the customer was charged a No-Show Fee ### Cash Not Received The following condition should be met: * **Cash Not Dispensed** - Some or all of the funds debited from the cardholder's account were not dispensed by the ATM or point of sale terminal ### Other The following condition should be met: * **Cardholder Dispute** - The dispute is about a transaction with a merchant or issues with the transaction itself, not problems with the issuer such as billing errors, credit balance transfers, account management issues, or other issuer-related matters # Filing a Dispute Source: https://docs.decisionly.com/filing Learn how to file disputes with the card network ## Filing a Case via API Filing submits a dispute to the card network on behalf of the cardholder. For context on where filing fits in the dispute lifecycle, see [What Are Disputes?](/guide#the-dispute-lifecycle). You can file a case using the [file case endpoint](/api-reference/v2-cases/file-a-case). ```bash File a case with auto mode theme={null} curl https://api.decisionly.com/v2/issuer/cases/case_abc123/file \ -u test_d0019b48d05849a6: \ -X POST \ -H "Content-Type: application/json" \ -d '{ "file_mode": "auto" }' ``` ```bash File a case with chargeback mode theme={null} curl https://api.decisionly.com/v2/issuer/cases/case_abc123/file \ -u test_d0019b48d05849a6: \ -X POST \ -H "Content-Type: application/json" \ -d '{ "file_mode": "chargeback" }' ``` Once a case is filed with the card network, it cannot be modified or deleted. ## file\_mode Options Cases support two filing modes: **`auto`** - Your workflow rules will be evaluated and Decisionly will determine whether the case should be filed. This is the recommended mode for most use cases. **`chargeback`** - Decisionly will attempt to file the case as a chargeback, regardless of your workflow rules. Use this when you want to bypass workflow rule evaluation. ## Queueing a Case That Is Too Early to File Some card networks require a waiting period before filing for dispute types, for example a `credit_not_processed` chargeback cannot be filed until 15 days after the refund promise date for Visa. See [Filing Timelines](/filing-timelines) for the waiting period that applies to each network and dispute reason. If you file a case before its waiting period has passed, the request fails with a `filing_too_early` validation error. Instead of tracking the earliest filing date yourself and retrying, you can pass `queue_if_too_early` to queue the case for automatic filing: ```bash Queue a case that is too early to file theme={null} curl https://api.decisionly.com/v2/issuer/cases/case_abc123/file \ -u test_d0019b48d05849a6: \ -X POST \ -H "Content-Type: application/json" \ -d '{ "file_mode": "auto", "queue_if_too_early": true }' ``` If the case is blocked only by a waiting period, the request returns `202 Accepted` and the case is queued. Decisionly will automatically file once its waiting period has passed. If you use file\_mode `auto`, your workflow rules will be run first, and the case will only be queued if it would have been filed but for the waiting period. You can track queued cases through [webhooks](/webhooks): `case.queued` fires when the case is queued, `case.chargeback_filed` fires when it is later filed, and `case.chargeback_needs_review` fires if the case needs manual review. Queueing is opt-in. Without `queue_if_too_early`, a case that is too early to file is rejected with a `filing_too_early` error and is never queued. The flag has no effect when the case fails validation for any other reason — those requests still return `400` with the full list of errors. # Filing Requirements Source: https://docs.decisionly.com/filing-requirements Required fields and documentation for each dispute type and card network Depending on dispute reason and card network, different fields and documentation must be present when you call the file endpoint for a case. Missing values produce a `400` response with `parameter_missing` or `documentation_missing` errors. This reference lists, per network, the requirements for each dispute type. Evidence beyond these requirements is also recommended, see [Dispute Types](/dispute-types). ## Mastercard ### Required fields | Reason | Required fields | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `fraud` | `issuer_evidence.card.is_active` (must be `false`); at least one of `issuer_evidence.fraud.was_reported` or `issuer_evidence.fraud.submit_report` | | `incorrect_amount` | `issuer_evidence.amount_correction.amount`, `issuer_evidence.amount_correction.currency` | ### Required documentation | Reason | Required file category | | ---------------------------------- | --------------------------- | | `incorrect_amount` | `transaction_receipt` | | `paid_by_other_means` | `prior_transaction_receipt` | ## Visa ### Required fields | Reason | Required fields | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `canceled_or_returned` | `issuer_evidence.delivery.date` or `issuer_evidence.delivery.expected_date`, `issuer_evidence.merchant_contact.date` | | `credit_not_processed` | `issuer_evidence.refund.promise_date` | | `duplicate_charge` | `issuer_evidence.prior_transaction.arn` | | `fraud` | `issuer_evidence.card.is_active` (must be `false`); at least one of `issuer_evidence.fraud.was_reported` or `issuer_evidence.fraud.submit_report` | | `incorrect_amount` | `issuer_evidence.amount_correction.amount`, `issuer_evidence.amount_correction.currency` | | `paid_by_other_means` | `issuer_evidence.merchant_contact.date` | | `product_counterfeit` | `issuer_evidence.delivery.date` | | `product_not_as_described` | `issuer_evidence.delivery.date`, `issuer_evidence.merchant_contact.date` | | `product_not_received` | `issuer_evidence.delivery.expected_date`, `issuer_evidence.merchant_contact.date` | | `subscription_canceled` | `issuer_evidence.cancellation.date`, `issuer_evidence.merchant_contact.date` | ### Required documentation | Reason | Required file category | | ----------------------------------- | ------------------------------------------------------------------------------------------------------- | | `credit_not_processed` | `refund_promise` (credit transaction receipt, voided transaction receipt, or other proof of credit due) | | `incorrect_amount` | `transaction_receipt` | | `paid_by_other_means` | `prior_transaction_receipt` | | `product_counterfeit` | `counterfeit_evidence` (e.g. photo of counterfeit item, third-party verification) | ## American Express ### Required fields | Reason | Required fields | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `fraud` | `issuer_evidence.card.is_active` (must be `false`); at least one of `issuer_evidence.fraud.was_reported` or `issuer_evidence.fraud.submit_report` | | `incorrect_amount` | `issuer_evidence.amount_correction.amount`, `issuer_evidence.amount_correction.currency` | ### Required documentation | Reason | Required file category | | ---------------------------------- | --------------------------- | | `incorrect_amount` | `transaction_receipt` | | `paid_by_other_means` | `prior_transaction_receipt` | For the full list of recommended evidence per dispute type, see the [Dispute Types](/dispute-types) documentation. For filing windows and earliest-filing dates, see [Filing Timelines](/filing-timelines). # Filing Timelines Source: https://docs.decisionly.com/filing-timelines Filing windows for each dispute type and card network Each card network sets its own timing rules for when disputes can be filed and how long issuers have to file. This reference lists, per network, the earliest and latest filing dates for each dispute type. * **Earliest filing** is the soonest a dispute can be submitted after the reference event. Where blank, disputes can be filed after the transaction settles. Disputes cannot be filed if the transaction is still pending. * **Latest filing** is the deadline. If missed, the dispute right is forfeited. The case will be automatically closed with status `expired` if the filing window is missed. ## Mastercard | Reason | Earliest filing | Latest filing | | --------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `canceled_or_returned` | 15 days after cancellation date or return date, if provided | 120 days from cancellation date, return date, or transaction date, up to 540 days from transaction date | | `cash_not_received` | 5 days after transaction date | 120 days from transaction date | | `credit_not_processed` | 15 days after refund promise date, if provided | 120 days from refund promise date or transaction date, up to 540 days from transaction date | | `duplicate_charge` | — | 90 days from transaction date | | `fraud` | — | 120 days from transaction date | | `incorrect_amount` | — | 90 days from transaction date | | `invalid_authorization` | — | 90 days from transaction date | | `other` | — | 120 days from transaction date | | `paid_by_other_means` | — | 90 days from transaction date | | `product_counterfeit` | After delivery date, if provided | 120 days from transaction date | | `product_not_as_described` | 15 days after delivery date or cancellation date, if provided, otherwise 15 days after transaction date | 120 days from delivery date, cancellation date, service end date, or transaction date, up to 540 days from transaction date | | `product_not_received` | After expected delivery date, if provided | 120 days from expected delivery date, service end date, or transaction date, up to 540 days from transaction date | | `subscription_canceled` | — | 120 days from transaction date | ### Mastercard single message system Mastercard debit single message transactions have differences in filing timelines from Mastercard credit transactions. | Reason | Earliest filing | Latest filing | | --------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | `canceled_or_returned` | 5 days after transaction date, and 15 days after cancellation date or return date, if provided | 120 days from cancellation date, return date, or transaction date, up to 540 days from transaction date | | `cash_not_received` | 5 days after transaction date | 120 days from transaction date | | `credit_not_processed` | 5 days after transaction date, and 15 days after refund promise date, if provided | 120 days from refund promise date or transaction date, up to 540 days from transaction date | | `duplicate_charge` | — | 90 days from transaction date | | `fraud` | — | 120 days from transaction date | | `incorrect_amount` | — | 90 days from transaction date | | `invalid_authorization` | — | 90 days from transaction date | | `other` | 5 days after transaction date | 120 days from transaction date | | `paid_by_other_means` | — | 90 days from transaction date | | `product_counterfeit` | 5 days after transaction date | 120 days from transaction date | | `product_not_as_described` | 5 days after transaction date, and 15 days after delivery date or cancellation date, if provided | 120 days from delivery date, cancellation date, service end date, or transaction date, up to 540 days from transaction date | | `product_not_received` | 5 days after transaction date, and after expected delivery date, if provided | 120 days from expected delivery date, service end date, or transaction date, up to 540 days from transaction date | | `subscription_canceled` | 5 days after transaction date | 120 days from transaction date | ## Visa | Reason | Earliest filing | Latest filing | | --------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `canceled_or_returned` | 15 days after cancellation date or return date, if provided | 120 days from cancellation date, return date, or transaction date, up to 540 days from transaction date | | `cash_not_received` | — | 120 days from transaction date | | `credit_not_processed` | 15 days after refund promise date | 120 days from refund promise date, up to 540 days from transaction date | | `duplicate_charge` | — | 120 days from transaction date | | `fraud` | — | 120 days from transaction date | | `incorrect_amount` | — | 120 days from transaction date | | `invalid_authorization` | — | 75 days from transaction date | | `other` | — | 120 days from transaction date | | `paid_by_other_means` | — | 120 days from transaction date | | `product_counterfeit` | After delivery date | 120 days from delivery date or transaction date, up to 540 days from transaction date | | `product_not_as_described` | 15 days after delivery date or cancellation date, if provided, otherwise 15 days after transaction date | 120 days from delivery date, cancellation date, service end date, or transaction date, up to 540 days from transaction date | | `product_not_received` | 15 days after expected delivery date | 120 days from expected delivery date, service end date, or transaction date, up to 540 days from transaction date | | `subscription_canceled` | — | 120 days from transaction date | ## American Express | Reason | Earliest filing | Latest filing | | --------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------ | | `canceled_or_returned` | 15 days after cancellation date or return date, if provided, otherwise 15 days after transaction date | 120 days from transaction date | | `cash_not_received` | — | 120 days from transaction date | | `credit_not_processed` | 15 days after refund promise date, if provided, otherwise 15 days after transaction date | 120 days from transaction date | | `duplicate_charge` | — | 120 days from transaction date | | `fraud` | — | 120 days from transaction date | | `incorrect_amount` | — | 120 days from transaction date | | `invalid_authorization` | — | 120 days from transaction date | | `other` | — | 120 days from transaction date | | `paid_by_other_means` | — | 120 days from transaction date | | `product_counterfeit` | After delivery date, if provided | 120 days from transaction date | | `product_not_as_described` | 15 days after delivery date or cancellation date, if provided, otherwise 15 days after transaction date | 120 days from transaction date | | `product_not_received` | After expected delivery date, if provided | 120 days from transaction date | | `subscription_canceled` | — | 120 days from transaction date | For required and recommended evidence per dispute type, see [Dispute Types](/dispute-types). For network-specific required fields and documentation, see [Filing Requirements](/filing-requirements). # Fraud Liability Source: https://docs.decisionly.com/fraud-liability Network data checks for fraud disputes For fraud disputes, Decisionly retrieves authorization and clearing data from the card network after you create a case to determine if chargeback rights exist. For background on how authentication methods affect liability, see [What Are Disputes?](/guide#liability-and-authentication). ## How Fraud Liability Works When you create a fraud case, Decisionly automatically checks authorization and clearing data in the background for conditions that shift liability from the merchant to the issuer - things like 3D Secure authentication, a tokenized transaction, or a verified PIN. The exact set of checks depends on the card network. If any of these conditions are detected, the case cannot be filed because the card network will deny the chargeback. This doesn't mean the cardholder's fraud claim is invalid - it means you cannot hold the merchant liable for the transaction. The issuer may still need to reimburse the cardholder, but cannot recover funds from the merchant via chargeback. ## Workflow Rules You can configure [workflow rules](/workflow-rules) to control how fraud cases are handled based on the liability result. The workflow rule to set up is **Issuer has Liability**. This rule determines whether the issuer is liable for the fraud based on network data. You could use this rule to **accept liability** or **flag for review** when the issuer is liable. # What Are Disputes? Source: https://docs.decisionly.com/guide What disputes are, how they work, and what you need to know as an issuer When a cardholder sees a transaction on their statement that they believe is wrong, they can ask their issuer to reverse it. This reversal process is called a **dispute** — and as an issuer, managing disputes is one of your core responsibilities. Disputes can also be known as **chargebacks** — a chargeback generally refers to a dispute that has been filed with the network. This guide explains how disputes work, from the regulations that require them to the card network rules that govern them. If you're new to dispute processing, start here before diving into the API documentation. **Issuer** — the bank or financial institution that issued the card to the cardholder. If you are a fintech or processor managing disputes, consider yourself the issuer for the purposes of this guide. **Acquirer** — the bank or payment processor on the merchant's side. The acquirer receives your dispute and works with the merchant to respond. ## Why Cardholders Dispute Charges Disputes fall into two broad categories based on what the cardholder is claiming: * **Fraud disputes** — the cardholder says they didn't make or authorize the transaction. Someone else used their card. * **Merchant disputes** — the cardholder acknowledges the transaction but claims something went wrong. The product never arrived, was defective, or the merchant didn't process a refund. These two categories follow different rules throughout the dispute process — different liability models, different evidence requirements, and in some networks, different dispute flows entirely. For a full list of the dispute types supported by Decisionly, see [Dispute Types](/dispute-types). ## Fraud Disputes In a fraud dispute, the cardholder is asserting that they did not participate in the transaction at all. The card may have been stolen, the number compromised in a data breach, or used by someone with access to the cardholder's account. Before filing a fraud dispute, you must cancel the compromised card and report the fraud to the card network's fraud database. These are hard requirements — the networks will reject the dispute without them. Decisionly will help with reporting the fraud but it is your responsibility to cancel the card. ### Liability and Authentication Not every fraud claim results in the merchant bearing the cost. In general, the issuer is liable for card present fraud, while the merchant is liable for card not present fraud. The card networks use a **liability framework** to determine who is financially responsible for a fraudulent transaction, and that determination depends largely on how the transaction was authenticated. **Liability shift** — a rule that moves financial responsibility for fraud from one party to another based on how the transaction was processed. If the merchant used a stronger authentication method, liability may shift away from them and back to the issuer. The core principle is straightforward: the party that failed to use available security measures bears the liability. **Card-present transactions** (in-store, at a terminal): * **EMV chip** — if the merchant's terminal read the chip, liability for counterfeit fraud shifts to the issuer. If the merchant didn't support chip and fell back to the magnetic stripe, the merchant bears liability. * **PIN verification** — a PIN-verified transaction is strong evidence that the cardholder (or someone who knew the PIN) was present. This makes fraud chargebacks difficult to win. * **Contactless/tap** — generally follows the same liability rules as chip transactions. * **Digital wallets** (Apple Pay, Google Pay, Samsung Pay) — these use **tokenization**, replacing the actual card number with a device-specific token. A tokenized transaction is strong evidence that the cardholder's enrolled device was present, making fraud chargebacks very difficult to pursue. Digital wallet transactions generally follow the same liability rules as chip transactions. **Card-not-present transactions** (online, phone, mail order): * **3-D Secure (3DS)** — an authentication protocol (branded as Visa Secure, Mastercard Identity Check, or Amex SafeKey) where the cardholder verifies their identity during checkout, typically through their banking app or a one-time code. A fully authenticated 3DS transaction shifts fraud liability to the issuer and may block the chargeback entirely. * **CVV/CVC (Card Verification Value/Card Validation Code)** — the three or four digit security code printed on the card. A CVV match provides some evidence the cardholder had the physical card, but does not trigger a liability shift. * **AVS (Address Verification Service)** — compares the billing address provided by the buyer against the address on file with the issuer. Like CVV, a match is supporting evidence but does not shift liability. When you receive a fraud dispute, the transaction data will tell you which authentication methods were used. If the merchant used 3DS or read the chip, the chargeback may be ineligible. Decisionly validates these conditions automatically and will reject cases that cannot be filed — see [Fraud Liability](/fraud-liability) for details. ## Merchant Disputes Merchant disputes cover situations where the cardholder acknowledges making the purchase but has a legitimate complaint — goods not received, a missing refund, a duplicate charge, and so on. The card networks generally expect the cardholder to attempt to resolve the issue with the merchant before filing. **Representment** — when the merchant (through the acquirer) responds to a dispute with evidence that the original transaction was valid. The merchant is "re-presenting" the transaction. When you file a merchant dispute, the merchant can respond with **compelling evidence** to prove the transaction was legitimate. The core question varies by dispute type — did the goods arrive? Was the refund already issued? Were the charges actually distinct transactions? — but the burden is on the merchant to demonstrate that the cardholder's claim doesn't hold up. If a merchant responds with evidence, the dispute is reversed through representment and you must decide whether to accept or escalate. For the full list of dispute types and evidence requirements, see [Dispute Types](/dispute-types). For filing windows, see [Filing Timelines](/filing-timelines). ## First-Party Fraud Not all disputes are legitimate. **First-party fraud** (sometimes called friendly fraud) occurs when a cardholder files a dispute for a transaction they actually made and benefited from. Common patterns include: * Claiming a purchase wasn't received when it was * Disputing a subscription charge they forgot to cancel * Regretting a purchase and using a dispute instead of the merchant's return process * A family member made the purchase but the cardholder doesn't recognize it * The cardholder doesn't recognize the **billing descriptor** on their statement — the merchant's legal entity name or payment processor name may look nothing like the brand the cardholder purchased from **Billing descriptor** — the merchant name that appears on the cardholder's statement (also known as the statement descriptor). This can be a source of confusion: a cardholder might buy from "Joe's Coffee Shop" but see "ACME FOOD SERVICES LLC" on their statement. Unrecognized descriptors are a common cause of unnecessary fraud disputes. First-party fraud is a rapidly accelerating problem for issuers and merchants. From the issuer's perspective, it can be difficult to distinguish first-party fraud from legitimate disputes. Decisionly can help by reviewing dispute and transaction data and flagging potential abuse flags. If a merchant submits compelling evidence, this can also help identify cases of first-party fraud. ## How Card Types Differ Not all cards follow the same dispute rules. Two distinctions matter most: * **Consumer vs. commercial** — consumer card disputes (personal credit and debit cards) are governed by federal regulations (Regulation Z for credit, Regulation E for debit) that mandate investigation timelines, provisional credits, and resolution deadlines. . * **Credit vs. debit** — consumer credit card disputes fall under Regulation Z, with longer resolution windows. Consumer debit card disputes fall under Regulation E, which imposes tighter timelines — you must provisionally credit the account within 10 business days, because the cardholder's own funds (not a credit line) are at stake. Prepaid cards generally follow the same rules as debit. See [Deadlines](#deadlines) for the specific regulatory requirements. ## The Dispute Lifecycle A chargeback is a multi-stage process with escalation points. At each stage, one party can accept the outcome or push the dispute further. The process varies slightly across different card networks, but typically follows this standard pattern: ```mermaid theme={null} flowchart TD A[Dispute Intake] --> B{File?} B -->|Reject / Write off| Z1[Case Closed] B -->|File| C[Chargeback Filed] C --> D{Merchant response} D -->|Accepts / No response| Z2[Won] D -->|Represents| E[Representment] E --> F{Accept evidence?} F -->|Yes| Z3[Lost] F -->|No| G[Pre-Arbitration] G --> H{Acquirer response} H -->|Accepts| Z4[Won] H -->|Declines| I[Arbitration] I --> J{Network ruling} J -->|Issuer favored| Z5[Won] J -->|Acquirer favored| Z6[Lost] style Z1 fill:#94a3b8,stroke:#64748b style Z2 fill:#4ade80,stroke:#22c55e style Z3 fill:#f87171,stroke:#ef4444 style Z4 fill:#4ade80,stroke:#22c55e style Z5 fill:#4ade80,stroke:#22c55e style Z6 fill:#f87171,stroke:#ef4444 ``` ### 1. Intake and Evaluation At dispute intake, the issuer gathers information from the cardholder about the reason for the dispute and any additional evidence the cardholder may have. Then, the issuer can investigate the transaction and/or issue a provisional credit if needed (for consumer debit cards, Regulation E requires this within 10 business days — see [Deadlines](#deadlines)). Based on your investigation, you decide whether to **file** the dispute, **reject** the case if you determine the cardholder should be liable, or **accept** the case if you will accept liability as the issuer. Each dispute must meet specific criteria — filing disputes that don't can lead to reversals and network fines. Decisionly automates the dispute evaluation and decisioning process so that you can programmatically file, reject or accept cases based on network rules and your own criteria. ### 2. Chargeback If you decide to file, the dispute is submitted to the card network. The disputed funds are debited from the acquirer/merchant and settled back to you, offsetting the provisional credit you already issued to the cardholder. The filing process requires specific documentation to be submitted to the network in accordance with network rules. Decisionly automatically files disputes into the card network using direct integrations with network dispute infrastructure. ### 3. Representment The acquirer and merchant review the dispute and decide how to respond. They can: * **Accept** the dispute — the merchant absorbs the loss and the case is closed * **Represent** — the merchant submits compelling evidence to contest the dispute. If the merchant represents, you receive their evidence and must decide whether it resolves the dispute. ### 4. Pre-Arbitration If you believe the merchant's representment evidence is insufficient, you can escalate to **pre-arbitration**. This is a final attempt to resolve the dispute between the issuer and acquirer before involving the card network. The acquirer can accept the pre-arbitration (funds return to the cardholder) or decline it, which sets the stage for arbitration. Pre-arbitration signals intent to escalate. Both parties should weigh the disputed amount and the strength of the case against the cost of proceeding to arbitration. ### 5. Arbitration If pre-arbitration fails, either party can file for **arbitration**. At this stage, the card network itself reviews the case and makes a binding decision. Arbitration fees are substantial. Because of the cost and finality, most disputes are resolved before reaching arbitration. It is generally reserved for high-value disputes where neither party is willing to concede. For how these stages map to the Decisionly API, see [Case Lifecycle](/case-lifecycle). You can track the dispute lifecycle in real time using [webhooks](/webhooks). ## How the Card Networks Differ While the overall dispute process follows the same pattern across networks, each card network has its own rules, terminology, and systems. ### Mastercard Mastercard's standard flow uses the terminology **first dispute** and **second presentment** (representment). After second presentment, cases can proceed to pre-arbitration and then arbitration. Mastercard also supports a **collaboration** flow for certain cardholder disputes. When a dispute is filed, the merchant can offer to resolve the issue by promising to refund the cardholder. If the merchant commits to a refund through collaboration, the dispute is paused — the expectation is that the merchant will issue the credit without the dispute needing to proceed further. If the merchant promises a refund through collaboration but fails to deliver it, the issuer can file a **follow-up chargeback** to recover the funds. This ensures the cardholder is made whole even when a merchant doesn't honor their commitment. Decisionly translates these to our [normalized dispute types](/dispute-types) automatically. * **4808** — Authorization-related * **4834** — Point-of-interaction errors (duplicate charges, incorrect amounts) * **4837, 4870, 4871** — Fraud (no cardholder authorization, chip liability shift) * **4853** — Cardholder disputes (goods not received, not as described, canceled recurring) ### Visa Visa uses two distinct dispute flows depending on the category: **Allocation** (fraud and authorization disputes): Visa automatically assigns initial liability based on the transaction data and the specific dispute condition. For example, if a card-not-present fraud dispute is filed and the merchant didn't use 3DS, Visa allocates liability to the acquirer immediately. The acquirer's only recourse is to respond through pre-arbitration — there is no representment step. This makes the allocation flow faster but gives the merchant fewer opportunities to respond. **Collaboration** (processing errors and consumer disputes): This flow more closely resembles the traditional dispute process. The issuer files a dispute, the acquirer responds with a dispute response (similar to representment), and if the dispute isn't resolved, either party can initiate pre-arbitration. This back-and-forth exchange gives both sides more opportunity to present evidence before escalating. Decisionly translates these to our [normalized dispute types](/dispute-types) automatically. * **10 — Fraud** (counterfeit, card-not-present, etc.) * **11 — Authorization** (no authorization obtained, declined authorization) * **12 — Processing Errors** (duplicate processing, incorrect amount, incorrect currency) * **13 — Consumer Disputes** (merchandise not received, not as described, etc.) Categories 10 and 11 use the allocation flow. Categories 12 and 13 use the collaboration flow. ### American Express American Express operates through **AEGNS** (American Express Global Network Services). Unlike its proprietary card business where Amex is both issuer and network, AEGNS has separate issuers and acquirers — similar to Visa and Mastercard. The dispute flow follows the same general pattern of dispute, representment, pre-arbitration, and arbitration, with 45-day response windows at each stage. Decisionly translates these to our [normalized dispute types](/dispute-types) automatically. Amex uses ISO 4500–4999 range codes. * **4521** — Authorization (invalid authorization) * **4507, 4512, 4523, 4530, 4536, 4752** — Processing errors (incorrect amount, multiple processing, currency discrepancy, late presentment) * **4513, 4515, 4544, 4553, 4554** — Cardmember disputes (credit not presented, paid by other means, canceled recurring, not as described, goods not received) * **4527, 4534, 4540, 4755, 4763, 4798, 4799** — Fraud (missing imprint, card not present, fraud full recourse, liability shift counterfeit/lost/stolen) ## Deadlines Disputes operate under strict deadlines set by both federal regulations and card network rules. Missing a deadline can mean being out of regulatory compliance or losing the right to dispute a transaction via the network. ### Regulatory Deadlines In the United States, two federal regulations govern how quickly you must act when a **consumer** cardholder reports a dispute. These regulations do not apply to commercial card programs — for commercial cards, only the card network deadlines below apply. **Regulation Z** (Truth in Lending Act, implementing the **Fair Credit Billing Act**) — applies to **consumer credit cards**: * The cardholder has **60 days** from the statement date to report a billing error * You must acknowledge the dispute within **30 days** of receiving it * You must resolve the dispute within **two complete billing cycles** (and no more than 90 days) * You must issue a provisional credit while the investigation is pending **Regulation E** (Electronic Fund Transfer Act) — applies to **consumer debit and prepaid cards**: * The cardholder has **60 days** from the statement date to report an error * You must investigate and resolve the dispute within **10 business days** (or 20 business days for new accounts) * If you need more time, you can extend to **45 days**, but you must provisionally credit the cardholder's account within 10 business days * For point-of-sale debit transactions, the extended investigation period is **90 days** ### Card Network Deadlines On top of regulatory requirements, each card network sets its own filing windows. These deadlines determine how long you have to file a dispute after the transaction date (or after a triggering event like an expected delivery date). | Stage | Deadline | | ------------------------------------ | ------------------------------------------------------------------------- | | Filing (authorization-related) | 90 days from transaction date | | Filing (cardholder disputes) | 120 days from transaction date or triggering event | | Filing (fraud) | 120 days from transaction date | | Filing (point-of-interaction errors) | 90 days from transaction date | | Second presentment (representment) | 45 days | | Pre-arbitration response | 45 days | | Arbitration filing | 45 days from second presentment and 10 days from pre-arbitration rebuttal | Mastercard also requires a **15-day waiting period** for certain cardholder disputes (such as goods not as described or refund not processed) to give the cardholder time to attempt resolution with the merchant. | Stage | Deadline | | -------------------------- | -------------------------------------------------- | | Filing (fraud) | 120 days from transaction date | | Filing (authorization) | 120 days from transaction date | | Filing (processing errors) | 120 days from transaction date | | Filing (consumer disputes) | 120 days from transaction date or triggering event | | Pre-arbitration response | 30 days | | Arbitration filing | 10 days from pre-arbitration response | Visa also requires a **15-day waiting period** for certain cardholder disputes (such as goods not as described or refund not processed) to give the cardholder time to attempt resolution with the merchant. | Stage | Deadline | | ---------------------------------- | ------------------------------------------- | | Filing (most dispute types) | 120 days from network processing date | | Filing (fraud full recourse) | 120 days (365 days for high-risk merchants) | | Second presentment (representment) | 45 days | | Pre-arbitration / Good faith | No fixed deadline | | Arbitration filing | 45 days | Amex also requires a **15-day waiting period** for certain cardholder disputes (such as goods not as described or refund not processed) to give the cardholder time to attempt resolution with the merchant. For the specific filing windows for each dispute type, see [Filing Timelines](/filing-timelines). ## Dispute Outcomes Most disputes do not follow the full lifecycle to arbitration. Here's how cases can conclude: ### Merchant Accepted/Didn't Respond The most common outcome. The merchant (through the acquirer) either explicitly accepts the dispute or simply doesn't respond within the representment deadline. In either case, the cardholder keeps the provisional credit and the case is closed. In the Decisionly API, this results in a `won` status. ### Representment Accepted The merchant represents with compelling evidence that you find persuasive. You accept the representment, the provisional credit is reversed from the cardholder, and the case is closed with a `lost` status. Assessing representment evidence is a key part of the dispute process. You need to determine whether the merchant's documentation actually addresses the reason for the dispute — for example, whether a delivery receipt proves the cardholder received the goods, or whether a signed contract proves the cardholder agreed to the charges. Decisionly provides a evidence scoring system to help you evaluate representment evidence. ### Merchant Credited The merchant issues a refund directly to the cardholder outside the dispute process. Since the cardholder has been made whole, you withdraw the dispute, and reclaim any provisional credit that was offered. This results in a `merchant_credited` status. ### Withdrawn You can withdraw a dispute before it reaches a final resolution — for example, if the cardholder confirms they now recognize the transaction or resolves the issue directly with the merchant. This results in a `withdrawn` status. ### Rejected You may determine that the cardholder's claim doesn't warrant a dispute — for example, if you determine the cardholder’s claim is illegitimate or inaccurate. In this case, no provisional credit is issued and no dispute is filed. This results in a `rejected` status. ### Issuer Accepted Sometimes you may decide not to file a dispute even though the cardholder has a valid complaint. This typically happens when the disputed amount is too small to justify the operational cost of filing, or when the transaction data makes the case unlikely to succeed. You issue the cardholder a credit and absorb the loss yourself rather than pursuing it through the card network. This results in an `accepted` status — you've accepted liability on behalf of the cardholder without involving the merchant. You may also accept liability after a dispute has been filed — for example, if the merchant represents with compelling evidence and you decide it's not worth escalating to pre-arbitration, but you do not wish to hold the cardholder liable. This also results in an `accepted` status. ## The Decisionly API Decisionly provides a unified API for managing the entire dispute lifecycle across Visa, Mastercard, and American Express. Rather than integrating directly with each card network's proprietary system, you work with a single set of endpoints and data models. Here's how the key concepts in this guide map to the API: * **Creating a dispute** — submit transaction data, cardholder information, and evidence through the [Cases API](/api-reference/v2-cases/create-a-case) * **Filing** — trigger the dispute with the card network via the [File endpoint](/filing), using workflow rules or direct filing * **Tracking status** — monitor the dispute as it moves through representment, pre-arbitration, and arbitration via [case status](/case-lifecycle) and [webhooks](/webhooks) * **Evidence** — attach supporting documentation through the [Files API](/api-reference/v2-files/upload-a-file) * **Automation** — configure [workflow rules](/workflow-rules) to automatically file, reject, or escalate disputes based on your criteria Your role as the issuer is to make sure disputes are handled and resolved in line with regulations, network rules and your own business requirements. By configuring your disputes process with Decisionly, you can programmatically determine whether to file a dispute, what reason code to use, whether to accept representment or escalate, and more. Decisionly handles the operational complexity: network-specific message formatting, reason code translation, deadline tracking, routing to the correct network system, and [fraud liability](/fraud-liability). Decisionly also enables you to configure your custom workflows and dispute criteria and automates the evidence review. With Decisionly, you can focus on dispute strategy rather than individual dispute handling or network integration details. Create and file your first dispute Evidence requirements for each reason code Understand case statuses and transitions Get notified when case status changes # Introduction Source: https://docs.decisionly.com/introduction Get started with the Decisionly API to automate dispute filing The Decisionly API is organized around [REST](https://en.wikipedia.org/wiki/REST). The API has resource-oriented URLs, accepts [JSON-encoded](https://www.json.org/json-en.html) request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. ## Test Mode You can use the Decisionly API in test mode, which doesn't affect your live data or interact with the card networks. The API key you use to authenticate the request determines whether the request is live mode or test mode. ## Getting Started To get started: 1. Create a new API key from your [settings page](https://decisionly.com/settings) 2. Read the [Quickstart](/quickstart) guide to learn how to make your first request 3. Explore the API reference to learn about available resources and endpoints ## Base URL All API requests should be made to: ``` https://api.decisionly.com/v2/issuer ``` ## Need Help? Contact us at [support@decisionly.com](mailto:support@decisionly.com) # Pagination Source: https://docs.decisionly.com/pagination Learn how to paginate through list responses When an API response returns a list of objects, no matter the amount, pagination is supported. In paginated responses, objects are nested in a `data` property and have a `has_more` property that indicates whether you have reached the end of the last page. You can use the `starting_after` and `ending_before` query parameters to browse pages. ## Pagination Parameters Number of objects to return. Maximum of 100. Cursor for use in pagination. Return the next page starting after this object ID. Cursor for use in pagination. Return the previous page ending before this object ID. ## Example Request ```bash cURL theme={null} curl https://api.decisionly.com/v2/issuer/cases \ -u test_d0019b48d05849a6: \ -d starting_after="case_1MtJUT2eZvKYlo2CNaw2HvEv" \ -d limit=10 ``` ## Example Response ```json theme={null} { "has_more": false, "data": [ { "case_id": "case_b9d08d1a84f84b28b942b05f", // ... }, { "case_id": "case_652654a457d9423aae0e495a", // ... }, { "case_id": "case_d177a2a647ae4299abc2a320", // ... } ] } ``` # Quickstart Source: https://docs.decisionly.com/quickstart Learn how to file your first dispute with the Decisionly API Filing disputes is a time consuming and often confusing process. Use the Decisionly API to quickly and confidently file your disputes. Our API ensures that you will meet all the requirements and timelines for the type of dispute you wish to file. New to disputes? Read [What Are Disputes?](/guide) first to understand the dispute lifecycle, card network rules, and key terminology. Before you can make requests to the Decisionly API, you will need to grab your API key from your dashboard [settings](https://decisionly.com/settings). **Replace the sample API key.** The key `test_d0019b48d05849a6` used in these examples is for illustration only and will return an `Invalid API key` error. Substitute your real API key from the dashboard [settings](https://decisionly.com/settings). ## Step 1: Create a case Create a case with cardholder information, card details, transaction information, and dispute details: ```bash Create a case theme={null} curl https://api.decisionly.com/v2/issuer/cases \ -u test_d0019b48d05849a6: \ -H "Content-Type: application/json" \ -d '{ "cardholder": { "billing_address": { "city": "San Francisco", "country": "US", "line1": "742 Evergreen Terrace", "line2": "Unit 5B", "postal_code": "94102", "state": "CA" }, "email": "jane@example.com", "issuer_id": "9529456289", "name": "Jane Smith", "type": "individual" }, "dispute": { "amount": 2990, "currency": "USD", "date": "2026-04-20T00:00:00.000Z", "raised_by": "cardholder", "reason": "product_not_received" }, "issuer_evidence": { "cardholder_explanation": "I never received this order", "product": { "type": "merchandise" }, "delivery": { "expected_date": "2026-04-05T00:00:00.000Z" }, "merchant_contact": { "was_attempted": true, "date": "2026-04-08T00:00:00.000Z", "was_successful": false, "description": "Contacted merchant via email but received no response" } }, "merchant": { "category_code": "5812", "name": "FoodHub" }, "transaction": { "amount": 2990, "arn": "48162855246353338636162", "card": { "expiry_month": 12, "expiry_year": 2028, "last4": "4242", "network": "mastercard", "type": "credit" }, "currency": "USD", "date": "2026-03-28T00:00:00.000Z" } }' ``` **Keep dates within the filing window.** The `product_not_received` reason requires filing within 120 days of the transaction date. If `delivery.expected_date` is provided, filing must also be after that date. Replace the dates in this example with current transaction and delivery dates. ## Step 2: File the case File the case with the card network: ```bash File a case theme={null} curl https://api.decisionly.com/v2/issuer/cases/case_abc123/file \ -u test_d0019b48d05849a6: \ -X POST \ -H "Content-Type: application/json" \ -d '{ "file_mode": "auto" }' ``` Set `file_mode` to `auto` to let your workflow rules determine how the case should be filed, or `chargeback` to file the case as a chargeback. ## Next Steps Learn about the different dispute reasons and requirements Set up rules to automate your filing decisions # Reference IDs Source: https://docs.decisionly.com/reference-ids Link cases to your internal systems with reference IDs Reference IDs allow you to associate Decisionly cases with your internal system identifiers. These fields enable you to connect cardholders, cards, merchants, and transactions in Decisionly with your existing records. ## Available Reference IDs You can include reference IDs for the following entities: * **Cardholder ID** ([`cardholder.issuer_id`](/api-reference/v2-cases/create-a-case#body-cardholder-issuer-id-one-of-0)): Your unique identifier for the cardholder. * **Card ID** ([`card.issuer_id`](/api-reference/v2-cases/create-a-case#body-transaction-card-issuer-id-one-of-0)): Your unique identifier for the card (not the PAN) * **Merchant ID** ([`merchant.issuer_id`](/api-reference/v2-cases/create-a-case#body-merchant-issuer-id-one-of-0)): Your unique identifier for the merchant * **Transaction ID** ([`transaction.issuer_id`](/api-reference/v2-cases/create-a-case#body-transaction-issuer-id-one-of-0)): Your unique identifier for the transaction * **Program ID** ([`program_id`](/api-reference/v2-cases/create-a-case#body-program-id-one-of-0)): Your unique identifier for the card program the case belongs to Cardholder ID, Card ID, and Transaction ID are searchable in the Decisionly dashboard, making it easy to find cases using your internal identifiers. The Program ID field is unique in that cases can be configured to be filtered by card program in the dashboard UI. # Testing Source: https://docs.decisionly.com/testing Use test mode overrides to pass or fail evidence review When you create a case with a [test mode API key](/authentication#api-key-prefixes) (prefix `test_`), Decisionly recognizes special values for the issuer explanation and file category that bypass AI analysis and return mock [Evidence Review](/evidence-review) results. Use these to exercise both the pass and fail branches of your [workflow rules](/workflow-rules) without crafting realistic evidence and documents. These overrides only take effect on accounts using a `test_` API key. In live mode they're treated as regular values. ## Evidence Review and Fraud Liability overrides Include one of the values below anywhere in [`issuer_explanation`](/api-reference/v2-cases/create-a-case#body-issuer-evidence-issuer-explanation-one-of-0) on the case's [`issuer_evidence`](/api-reference/v2-cases/create-a-case#body-issuer-evidence) to replace the AI [Evidence Review](/evidence-review) result and/or [Fraud Liability](/fraud-liability) result for the case. For all dispute reasons: | `issuer_explanation` contains | Evidence Review result | | ----------------------------- | -------------------------------------------------------- | | `valid_evidence` | All conditions for the dispute reason marked **met** | | `invalid_evidence` | All conditions for the dispute reason marked **not met** | For fraud disputes, you can additionally control [Fraud Liability](/fraud-liability): | `issuer_explanation` contains | Fraud Liability result | | ----------------------------- | ------------------------------------------------------------ | | `merchant_liable` | Liability assigned to the merchant (chargeback rights exist) | | `issuer_liable` | Liability assigned to the issuer (no chargeback rights) | ## Documentation Review overrides Set a file's `category` to one of the values below when [uploading the file](/api-reference/v2-files/upload-a-file) to replace the AI [Documentation Review](/evidence-review) result for that file. The relevance check is skipped entirely. | File `category` value | Documentation Review result | | --------------------- | --------------------------------- | | `valid_document` | File marked as valid and relevant | | `invalid_document` | File marked as invalid | This is a per-file override — you can mix `valid_document` and `invalid_document` files in the same case. ## Example Upload a file with the `valid_document` category, then create a case that references it and uses `invalid_evidence` to force conditions review to fail: ```bash cURL theme={null} # 1. Upload a file with the valid_document test category curl https://api.decisionly.com/v2/issuer/files \ -u test_d0019b48d05849a6: \ -F "category=valid_document" \ -F "file=@receipt.pdf" # Response: { "id": "file_abc123", "category": "valid_document", ... } # 2. Create a case that forces the conditions check to fail curl https://api.decisionly.com/v2/issuer/cases \ -u test_d0019b48d05849a6: \ -H "Content-Type: application/json" \ -d '{ "dispute": { "reason": "product_not_received" }, "issuer_evidence": { "issuer_explanation": "invalid_evidence", "documentation": ["file_abc123"] } }' ``` How Documentation Review and Conditions Review work in production Configure how cases are handled based on evidence review results # API Versioning Source: https://docs.decisionly.com/versioning Understanding Decisionly API versions and changes The Decisionly API uses versioning to ensure backward compatibility while allowing us to improve the API over time. ## How Versioning Works The Decisionly API uses URL-based versioning. You specify the API version directly in the URL path of your requests. We will bump the API version for **breaking changes**. Non-breaking changes, such as adding new fields or endpoints, will not trigger a version bump. All API endpoints are versioned by including the version in the URL path. For example: * `https://api.decisionly.com/v2/issuer/cases` * `https://api.decisionly.com/v1/issuer/cases` ## Version History * **v2 (Current)** * **v1 (Legacy)** ## v2 Changes ### Terminal Statuses Terminal case states are now represented as distinct status values instead of using a generic `closed` status with a `closed_reason` field: **v1 behavior:** * Terminal cases had `status: "closed"` with a `closed_reason` field indicating the specific outcome * A single `case.closed` webhook was triggered for all terminal states **v2 behavior:** * Terminal states are now first-class status values: `accepted`, `rejected`, `expired`, `withdrawn`, `merchant_credited` * The `closed_reason` field has been removed * Each terminal status has its own dedicated webhook event: `case.accepted`, `case.rejected`, `case.expired`, `case.withdrawn`, `case.merchant_credited` * The `case.closed` webhook is deprecated See the [Case Lifecycle documentation](/case-lifecycle) for more details. ### File endpoint Cases are now filed using a [dedicated file endpoint](/api-reference/v2-cases/file-a-case). ### Evidence Structure Changes The `issuer_evidence` object has been reorganized in v2 for better clarity and consistency: **Field groupings:** * Amount corrections: `correct_amount` and `correct_currency` → `amount_correction.amount` and `amount_correction.currency` * Return shipping: `return.shipping_carrier` and `return.shipping_tracking` → `return.shipping.carrier` and `return.shipping.tracking_number` * Service end date: `service_end_date` → `service.end_date` * Resolution: Previously flat resolution fields are now organized into specific resolution type objects: * Product resolution fields → `product` object (order\_id, description, condition, type) * Cancellation fields → `cancellation` object (id, date, description, policy\_provided) * Refund fields → `refund` object (was\_promised, promise\_date, description) * Return fields → `return` object (date, was\_successful, description, policy\_provided, shipping) * Delivery fields → `delivery` object (date, expected\_date) * Service fields → `service` object (end\_date) * Card fraud fields → `card` object (lost\_date, is\_active, cardholder\_has\_possession, possession\_at\_transaction) **Boolean field renames:** * `merchant_contact.success` → `merchant_contact.was_successful` * `return.success` → `return.was_successful` * `refund.promised` → `refund.was_promised` * `card.active` → `card.is_active` **Other field renames:** * `cardholder_message` → `cardholder_explanation` * `explanation` → `issuer_explanation` * `merchant_contact.prohibited_description` → `merchant_contact.prohibited_reason` # Webhooks Source: https://docs.decisionly.com/webhooks Receive real-time updates about your cases With webhooks, your app can know when something happens in Decisionly, such as a chargeback being filed for a case. ## Registering Webhooks To register a new webhook, you need to have a URL that Decisionly can call. You can configure a new webhook from your dashboard [settings](https://decisionly.com/settings). Add your URL and pick the events you want to listen for. ## Consuming Webhooks When you receive a webhook request from Decisionly, check the `type` attribute to see what event caused it. ### Case Lifecycle Events * `case.created` - Triggered when a case is created * `case.chargeback_filed` - Triggered when a chargeback is filed with the card network * `case.chargeback_represented` - Triggered when merchant responds with evidence * `case.prearb_received` - Triggered when the merchant challenges a dispute via pre-arbitration (Visa allocation flow) * `case.prearb_filed` - Triggered when a pre-arbitration case is filed with the card network * `case.prearb_rebutted` - Triggered when a pre-arbitration is rebutted by the merchant * `case.arbitration_filed` - Triggered when an arbitration case is filed with the card network * `case.won` - Triggered when a cardholder wins a case * `case.lost` - Triggered when a cardholder loses a case * `case.accepted` - Triggered when issuer accepts liability * `case.rejected` - Triggered when a case is rejected * `case.expired` - Triggered when a case expires * `case.withdrawn` - Triggered when a case is withdrawn by the cardholder * `case.merchant_credited` - Triggered when a case is closed due to merchant credit You likely want to listen for case lifecycle events to trigger processes in your system such as cardholder communication and money movement. ### Queuing Events * `case.queued` - Triggered when a case is [queued for filing](/filing#queueing-a-case-that-is-too-early-to-file) because its network waiting period has not passed You may want to listen for case queuing events to trigger automated processes in your system or additional communication with the cardholder. ### Case Needs Review Events * `case.chargeback_needs_review` - Triggered when a chargeback requires manual review * `case.representment_needs_review` - Triggered when a representment requires manual review You may want to listen for case needs review events to trigger manual review processes in your system or additional communication with the cardholder. ### Case Deadline Events * `case.resolution_deadline_approaching` - Triggered 12 hours before the Reg E or Reg Z resolution deadline if one applies to the case You may want to listen for case deadline events to ensure you resolve the case before the deadline. ## Webhook Payload Webhooks do not contain any sensitive information. They only contain the IDs of the objects that were affected by the event. So for case events, the `data` attribute will contain the `case_id`. You should then call the API to fetch the case and verify the event. ### Example Webhook Payload ```json theme={null} { "event_id": "event_2d7448cda095419bbecf066446104e37", "created": "2026-04-01T17:36:24.494Z", "type": "case.chargeback_filed", "data": { "case_id": "case_db7fc63f5b6842c1bfb5ffd74b71a66d" } } ``` ## Responding to Webhooks You should return a `200` status code to acknowledge the webhook. If you return a different status code, Decisionly will retry the webhook in 30 minutes, up to 24 times (12 hours of retries). # Workflow Rules Source: https://docs.decisionly.com/workflow-rules Customize filing decisions with workflow rules Workflow rules let you customize how Decisionly handles cases during the filing process. ## How Workflow Rules Work When you file a case or claim, Decisionly runs and applies your workflow rules to determine what action to take. Workflow rules can: * **Flag cases for manual review** - Route cases to a review queue when conditions aren't met * **Auto-accept** - Automatically close cases that can't be filed * **Auto-reject** - Automatically reject cases based on your criteria * **Auto-file** - Automatically file cases that meet your criteria ## Integration with Validations Workflow rules can act on the results of Decisionly's validation checks: ### Fraud Liability When Decisionly detects that a fraud case cannot be filed (e.g., 3D Secure authenticated transactions), you can configure rules to automatically handle these cases. For example, auto-accept liability when chargeback rights don't exist. See [Fraud Liability](/fraud-liability) for the complete list of checks. ### Evidence Review Decisionly uses AI to analyze whether evidence guidelines are met and whether uploaded documentation is valid. You can configure rules to: * Flag cases for review when evidence guidelines aren't met * Flag cases for review when documentation is invalid or missing See [Evidence Review](/evidence-review) for details on what's analyzed. ## Configuring Workflow Rules Workflow rules are configured in your [Decisionly dashboard](https://www.decisionly.com/workflow). You can create rules based on: * Case attributes (dispute reason, amount, merchant category) * Validation results (fraud checks, conditions review, documentation review) * Custom fields ## Common Workflow Rule Examples ### Auto-Accept Automatically accept liability when a fraud case cannot be filed due to validations (e.g., 3DS authenticated), reducing manual effort on ineligible disputes. ### Manual Review Flag cases for manual review when required evidence guidelines aren't detected when uploaded evidence is marked as invalid or irrelevant by the AI review, ensuring you only file strong cases. ### Auto-File Automatically file cases that meet all evidence guidelines and have valid documentation, streamlining your workflow for clear-cut disputes.