Skip to main content
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? 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.
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.

​
Step 1: Create a case

Create a case with cardholder information, card details, transaction information, and dispute details: 
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: 
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

Dispute Types

Learn about the different dispute reasons and requirements

Workflow Rules

Set up rules to automate your filing decisions