---
name: chargeflow-api
description: Integrate Chargeflow dispute automation - route a merchant or platform intent to the right Chargeflow API endpoint, authenticate, and handle webhooks.
---

# Integrating the Chargeflow API

You are integrating Chargeflow, a chargeback/dispute automation platform. This file routes an intent to the right endpoint. Full docs index: https://0.0.0.0:3000/llms.txt (every page is markdown - append `.md` to any docs URL).

## Base URL, auth, and versioning

- Base URL: `https://api.chargeflow.io`
- Every path is versioned: `/public/2025-04-01/...` (current) or `/public/2024-03-18/...` (previous). Prefer 2025-04-01 unless an endpoint only exists in 2024-03-18 (noted below).
- Authenticate every request with the `x-api-key` header. Details: https://0.0.0.0:3000/docs/reference/api-fundamentals/authentication.md
- Verify credentials before anything else: `GET /public/2025-04-01/health-check/access-key` (200 = key is valid). Unauthenticated liveness: `GET /public/2025-04-01/health-check`.
- Test keys / sandbox: https://0.0.0.0:3000/docs/reference/api-fundamentals/test-credentials.md

## First decision: merchant or platform?

- **Merchant** - the user runs a store and wants their own disputes automated. Use the merchant endpoints below.
- **Platform / PSP** - the user serves many merchants and wants evidence generation or dispute management on their behalf. Use the platform endpoints below.

## Merchant intents (spec: https://0.0.0.0:3000/specs/openapi-merchants-2025-04-01.json)

| Intent | Call |
|---|---|
| List chargebacks / disputes | `GET /public/2025-04-01/disputes` (paginated) |
| Check one dispute's status | `GET /public/2025-04-01/disputes/{disputeId}` |
| Upload an evidence file (receipt, invoice) | `POST /public/2025-04-01/disputes/{disputeId}/evidence` (multipart) |
| Add subscription/billing history to a dispute | `POST /public/2025-04-01/disputes/{disputeId}/subscription` |
| Log a customer conversation as evidence | `POST /public/2025-04-01/customer-communication` |
| Add order/fulfillment data to a dispute | `POST /public/2024-03-18/disputes/{disputeId}/order` (2024-03-18 only) |
| Create a dispute record manually | `POST /public/2024-03-18/disputes` (2024-03-18 only) |
| List pre-chargeback alerts | `GET /public/2025-04-01/alerts` |
| Check one alert | `GET /public/2025-04-01/alerts/{alertId}` |
| Report an alert's resolution (merchant-managed model) | `POST /public/2025-04-01/alerts/{alertId}/outcome` |

Minimal first call:

```bash
curl https://api.chargeflow.io/public/2025-04-01/disputes \
  -H "x-api-key: $CHARGEFLOW_API_KEY"
```

## Platform intents (spec: https://0.0.0.0:3000/specs/openapi-platforms-2025-04-01.json)

| Intent | Call |
|---|---|
| Onboard a merchant (create their account entity) | `POST /public/2025-04-01/accounts` |
| Fetch a merchant account | `GET /public/2025-04-01/accounts/{accountId}` |
| Create a dispute record for a merchant | `POST /public/2025-04-01/platform/disputes` |
| Generate an AI evidence package (EaaS) | `POST /public/2025-04-01/evidence` |
| Fetch a generated evidence package | `GET /public/2025-04-01/evidence/{evidenceId}` |

Evidence generation is async: submit, then wait for the `evidence.ready` webhook (or poll `GET /evidence/{evidenceId}`). Guide: https://0.0.0.0:3000/docs/platforms/eaas/generate-and-regenerate.md

## Webhooks (react instead of polling)

Register an endpoint with `POST /public/2024-03-18/webhooks` (registration lives in the 2024-03-18 version; list with GET, remove with DELETE on the same path). Merchant events: `dispute.created`, `alerts.created`, `alerts.transaction.linked`, `alerts.updated`. Platform events: `evidence.ready`, `evidence.error`, `integration.access.error`. Payload references: https://0.0.0.0:3000/docs/merchants/webhook-events/overview.md and https://0.0.0.0:3000/docs/platforms/webhook-events/overview.md. Setup guide: https://0.0.0.0:3000/docs/merchants/automation/subscribe-to-events.md

## Rules

- Never invent endpoints or fields - the OpenAPI specs above are the source of truth.
- Handle 429 by honoring `Retry-After`; handle errors per https://0.0.0.0:3000/docs/reference/api-fundamentals/error-handling.md and https://0.0.0.0:3000/docs/reference/error-codes.md
- Paginate list endpoints per https://0.0.0.0:3000/docs/reference/api-fundamentals/pagination.md
- Keep the API key server-side; never ship it to a browser.
- Product vocabulary (Prevent / Alerts / Automation / Connect): https://0.0.0.0:3000/docs/start-here/product-model.md