Quickstart

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: Run the workflow

Run your workflow rules for the case.

curl https://api.decisionly.com/v2/issuer/cases/case_abc123/run_workflow \
  -u test_d0019b48d05849a6: \
  -X POST

A 202 Accepted response means Decisionly accepted the case for evaluation filed. Your workflow rules decide whether to file it. See Filing a Dispute for the full behavior.

Getting Started

Core Concepts

Filing

Workflow and Validations

Step 1: Create a case

Step 2: Run the workflow

Next Steps

Dispute Types

Workflow Rules

​Step 1: Create a case

​Step 2: Run the workflow

​Next Steps

Dispute Types

Workflow Rules

Step 1: Create a case

Step 2: Run the workflow

Next Steps