# Submit platform disputes (https://docs.chargeflow.io/docs/platforms/eaas/submit-platform-disputes)



Use this endpoint to create dispute records in Chargeflow directly from your platform. This is useful when Chargeflow is not automatically ingesting disputes from a connected PSP, for example when your platform is the authoritative source of dispute data, or when you're operating in a bring-your-own-disputes model.

## Create a dispute [#create-a-dispute]

```
POST /public/2025-04-01/platform/disputes
```

### Request fields [#request-fields]

| Field          | Type              | Required | Description                                                                                                 |
| -------------- | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `account_id`   | string            | Yes      | The Chargeflow account ID of the merchant this dispute belongs to.                                          |
| `source_id`    | string            | Yes      | Your PSP's dispute ID, the unique identifier from the processor where the dispute originated.               |
| `created_at`   | ISO 8601 datetime | Yes      | When the dispute was created at the processor.                                                              |
| `reason`       | enum              | Yes      | The dispute reason code. See below for valid values.                                                        |
| `due_by`       | ISO 8601 datetime | Yes      | The evidence submission deadline.                                                                           |
| `amount`       | number            | Yes      | Disputed amount in the transaction currency. Must be ≤ the transaction amount.                              |
| `currency`     | string            | Yes      | Three-letter ISO 4217 currency code in uppercase (e.g., `USD`).                                             |
| `status`       | enum              | Yes      | Current dispute status. Must be `needs_response`, `under_review`, `won`, or `lost`.                         |
| `stage`        | enum              | No       | Dispute stage. One of: `Chargeback`, `Inquiry`, `Pre_arbitration`, `Arbitration`. Defaults to `Chargeback`. |
| `transaction`  | object            | No       | Transaction details. Recommended for stronger evidence. See below.                                          |
| `subscription` | object            | No       | Subscription details, if the disputed charge is subscription-related.                                       |
| `order`        | object            | No       | Order details including products, customer, shipping address, and fulfillment tracking.                     |

### Dispute reason values [#dispute-reason-values]

| Value                        | Description                                                         |
| ---------------------------- | ------------------------------------------------------------------- |
| `fraud`                      | Unauthorized transaction claim.                                     |
| `not_received`               | Customer claims goods or services were not received.                |
| `not_as_described`           | Customer claims goods or services differed from what was promised.  |
| `canceled_recurring_billing` | Customer claims a recurring charge continued after cancellation.    |
| `duplicate_charge`           | Customer claims they were charged more than once for the same item. |
| `credit_not_processed`       | Customer claims a refund was not applied.                           |
| `other`                      | Any reason not covered by the above.                                |

### Example request [#example-request]

<Tabs items="['curl', 'Node.js', 'Python']">
  <Tab value="curl">
    ```bash title="Terminal"
    curl -X POST https://api.chargeflow.io/public/2025-04-01/platform/disputes \
      -H "x-api-key: YOUR_PLATFORM_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "account_id": "66e6ea9ecd94925a9f8060d9",
        "source_id": "du_123456789",
        "created_at": "2025-04-15T08:30:00Z",
        "reason": "fraud",
        "due_by": "2025-04-29T23:59:00Z",
        "amount": 249.99,
        "currency": "USD",
        "status": "needs_response",
        "stage": "Chargeback",
        "transaction": {
          "source_id": "tx_1234567890",
          "account_id": "66e6ea9ecd94925a9f8060d9",
          "created_at": "2025-04-10T14:22:00Z",
          "type": "paid",
          "amount": 249.99,
          "currency": "USD",
          "payment_method": {
            "type": "card",
            "brand": "visa",
            "last4": "4242",
            "country": "US"
          }
        }
      }'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript title="Node.js"
    const res = await fetch('https://api.chargeflow.io/public/2025-04-01/platform/disputes', {
      method: 'POST',
      headers: {
        'x-api-key': process.env.CHARGEFLOW_PLATFORM_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        account_id: '66e6ea9ecd94925a9f8060d9',
        source_id: 'du_123456789',
        created_at: '2025-04-15T08:30:00Z',
        reason: 'fraud',
        due_by: '2025-04-29T23:59:00Z',
        amount: 249.99,
        currency: 'USD',
        status: 'needs_response',
        stage: 'Chargeback',
        transaction: {
          source_id: 'tx_1234567890',
          account_id: '66e6ea9ecd94925a9f8060d9',
          created_at: '2025-04-10T14:22:00Z',
          type: 'paid',
          amount: 249.99,
          currency: 'USD',
          payment_method: {
            type: 'card',
            brand: 'visa',
            last4: '4242',
            country: 'US',
          },
        },
      }),
    });
    const data = await res.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python title="Python"
    import os, requests

    res = requests.post(
        "https://api.chargeflow.io/public/2025-04-01/platform/disputes",
        headers={"x-api-key": os.environ["CHARGEFLOW_PLATFORM_API_KEY"]},
        json={
            "account_id": "66e6ea9ecd94925a9f8060d9",
            "source_id": "du_123456789",
            "created_at": "2025-04-15T08:30:00Z",
            "reason": "fraud",
            "due_by": "2025-04-29T23:59:00Z",
            "amount": 249.99,
            "currency": "USD",
            "status": "needs_response",
            "stage": "Chargeback",
            "transaction": {
                "source_id": "tx_1234567890",
                "account_id": "66e6ea9ecd94925a9f8060d9",
                "created_at": "2025-04-10T14:22:00Z",
                "type": "paid",
                "amount": 249.99,
                "currency": "USD",
                "payment_method": {
                    "type": "card",
                    "brand": "visa",
                    "last4": "4242",
                    "country": "US",
                },
            },
        },
    )
    data = res.json()
    ```
  </Tab>
</Tabs>

<Callout type="idea" title="Tip">
  Always include `transaction` data when available. Card verification results (3DS, AVS, CVC) are
  among the most impactful fields for fraud disputes.
</Callout>

## After creating the dispute [#after-creating-the-dispute]

Once the dispute record exists in Chargeflow you can:

* **Generate evidence** via the [EaaS Generate Evidence API](./generate-and-regenerate), referencing the returned dispute ID.
* **Enrich the dispute** with additional order or communication context before generating evidence.

## Next steps [#next-steps]

<Cards>
  <Card title="Generate & regenerate evidence" href="./generate-and-regenerate">
    Turn the dispute into a bank-ready PDF.
  </Card>

  <Card title="Monitor integration health" href="../monitor-integration-health">
    Confirm your platform key stays valid.
  </Card>
</Cards>