# API overview (https://docs.chargeflow.io/docs/api/2025-04-01/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 [#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](https://docs.chargeflow.io/docs/api/2025-04-01/merchants/health-check) |
| **Platforms API** | You are a platform or PSP recovering disputes for the merchants you serve | [Accounts](https://docs.chargeflow.io/docs/api/2025-04-01/platforms/accounts)         |

## Base URL and version [#base-url-and-version]

```
https://api.chargeflow.io/public/2025-04-01
```

The 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](https://docs.chargeflow.io/docs/api/2024-03-18) and the [migration guide](https://docs.chargeflow.io/docs/api/2025-04-01/migration) |

## Your first request [#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.

<Callout title="Before you start">
  You need an API access key. Generate one in the Chargeflow App under **Settings → Developers →
  Generate Keys**. See [API keys](https://docs.chargeflow.io/docs/reference/api-fundamentals/test-credentials).
</Callout>

<Tabs items="['curl', 'Node.js', 'Python']">
  <Tab value="curl">
    ```bash title="Terminal"
    curl -X GET https://api.chargeflow.io/public/2025-04-01/health-check/access-key \
      -H "x-api-key: YOUR_API_KEY"
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript title="Node.js"
    const res = await fetch('https://api.chargeflow.io/public/2025-04-01/health-check/access-key', {
      method: 'GET',
      headers: {
        'x-api-key': process.env.CHARGEFLOW_API_KEY,
      },
    });
    const data = await res.json();
    ```
  </Tab>

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

    res = requests.get(
        "https://api.chargeflow.io/public/2025-04-01/health-check/access-key",
        headers={"x-api-key": os.environ["CHARGEFLOW_API_KEY"]},
    )
    data = res.json()
    ```
  </Tab>
</Tabs>

Expected response:

```json title="Response"
"OK"
```

<Callout type="idea" title="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](https://docs.chargeflow.io/docs/reference/api-fundamentals/error-handling).
</Callout>

## Authentication [#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](https://docs.chargeflow.io/docs/reference/api-fundamentals/authentication).

## Environments [#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](https://docs.chargeflow.io/docs/reference/api-fundamentals/go-live-checklist) before you send production traffic. An isolated sandbox with separate test keys is coming: [Sandbox](https://docs.chargeflow.io/docs/merchants/sandbox).

## What every endpoint shares [#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](https://docs.chargeflow.io/docs/reference/api-fundamentals/pagination)         |
| Errors      | Standard HTTP status codes; every response carries a `requestId` to quote to support      | [Error handling](https://docs.chargeflow.io/docs/reference/api-fundamentals/error-handling) |
| Rate limits | A `429` means back off and honour `Retry-After`; published limits are coming              | [Rate limits](https://docs.chargeflow.io/docs/reference/api-fundamentals/rate-limits)       |
| Idempotency | An `Idempotency-Key` header applies to evidence generation today, not yet API-wide        | [Idempotency](https://docs.chargeflow.io/docs/reference/api-fundamentals/idempotency)       |
| Webhooks    | Register an endpoint per event and reply `200` to acknowledge                             | [Webhooks](https://docs.chargeflow.io/docs/reference/concepts/webhooks)                     |

## Next step [#next-step]

<Cards>
  <Card className="cf-card-outline" iconName="card-chip-1" title="Health check" href="/docs/api/2025-04-01/merchants/health-check">
    Run the first endpoint, then walk the merchant API in the order the sidebar lists it.
  </Card>
</Cards>

Building for a platform instead? Start at [Accounts](https://docs.chargeflow.io/docs/api/2025-04-01/platforms/accounts). Upgrading from the previous version? Read the [migration guide](https://docs.chargeflow.io/docs/api/2025-04-01/migration).