Get started
You are a developer about to call the Chargeflow API for the first time. This page gets you a real response in one call, then points at the mechanics every other endpoint shares.
What the API is for
The Chargeflow API is how you run dispute recovery from your own code instead of the dashboard. You use it to read disputes as they arrive, enrich them with the order, transaction, subscription, and customer-communication data that wins cases, upload evidence, act on pre-chargeback alerts, and receive webhooks when any of it changes.
Two surfaces, one API:
| Surface | Who it is for | Where it starts |
|---|---|---|
| Merchants API | You recover your own disputes | Health check |
| Platforms API | You are a platform or PSP recovering disputes for the merchants you serve | Accounts |
Base URL and version
https://api.chargeflow.io/public/2025-04-01The version is part of the path, so a request never silently changes behaviour.
| Version | Status | Reference |
|---|---|---|
2025-04-01 | Current | This section |
2024-03-18 | Legacy, still served | Legacy reference and the migration guide |
Your first request
Validate your key. It is the cheapest call in the API, it has no side effects, and it proves both authentication and connectivity in one shot.
Before you start
You need an API access key. Generate one in the Chargeflow App under Settings → Developers → Generate Keys. See API keys.
curl -X GET https://api.chargeflow.io/public/2025-04-01/health-check/access-key \
-H "x-api-key: YOUR_API_KEY"Expected response:
"OK"Tip
A 403 {"message":"Forbidden"} means the key is invalid or lacks permission. Call GET /public/2025-04-01/health-check to tell the two apart: a 200 there means the key is valid and the 403 was a permissions problem. See Error handling.
Authentication
Every endpoint requires the x-api-key header. HMAC signature validation is off by default and can be enabled in Settings → Developers; once on, requests also carry an x-chargeflow-hmac-sha256 signature over METHOD\nPATH\nBODY.
Full setup, including the signing walkthrough: Authentication.
Environments
There is one environment today. The keys you generate act on your live account, so read before you write and work through the go-live checklist before you send production traffic. An isolated sandbox with separate test keys is coming: Sandbox.
What every endpoint shares
| Mechanic | The short version | Full page |
|---|---|---|
| Pagination | offset (zero-based page index) and limit (default 25, max 100) on every list endpoint | Pagination |
| Errors | Standard HTTP status codes; every response carries a requestId to quote to support | Error handling |
| Rate limits | A 429 means back off and honour Retry-After; published limits are coming | Rate limits |
| Idempotency | An Idempotency-Key header applies to evidence generation today, not yet API-wide | Idempotency |
| Webhooks | Register an endpoint per event and reply 200 to acknowledge | Webhooks |
Next step
Building for a platform instead? Start at Accounts. Upgrading from the previous version? Read the migration guide.