# Quickstart (https://docs.chargeflow.io/docs/merchants/quickstart)



Get up and running with the Chargeflow API in five steps. By the end of this guide you will have authenticated, fetched disputes, enriched a dispute with evidence, and registered a webhook.

<Steps>
  <Step>
    ## Get your API key [#get-your-api-key]

    1. Log in to the [Chargeflow App](https://app.chargeflow.io/auth/sign-in).
    2. Navigate to **Settings → Developers**.
    3. Click **Generate Keys**.
    4. Copy your **API Access Key**.
  </Step>

  <Step>
    ## Validate your key [#validate-your-key]

    Confirm your key is active by hitting the key-validation health check:

    <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">
      If you receive a `403 {"message":"Forbidden"}` response, your API key is invalid. Return to Settings → Developers, revoke the existing key, and generate a new one.
    </Callout>
  </Step>

  <Step>
    ## List your disputes [#list-your-disputes]

    Fetch your first page of disputes:

    <Tabs items="['curl', 'Node.js', 'Python']">
      <Tab value="curl">
        ```bash title="Terminal"
        curl -X GET "https://api.chargeflow.io/public/2025-04-01/disputes?limit=5" \
          -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/disputes?limit=5', {
          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/disputes",
            headers={"x-api-key": os.environ["CHARGEFLOW_API_KEY"]},
            params={"limit": 5},
        )
        data = res.json()
        ```
      </Tab>
    </Tabs>

    The response returns a paginated list of dispute objects. Use the `id` field from any dispute to continue with the next step.
  </Step>

  <Step>
    ## Enrich a dispute [#enrich-a-dispute]

    Send targeted transaction data to strengthen the evidence Chargeflow uses when composing a rebuttal:

    <Tabs items="['curl', 'Node.js', 'Python']">
      <Tab value="curl">
        ```bash title="Terminal"
        curl -X PATCH https://api.chargeflow.io/public/2025-04-01/disputes/DISPUTE_ID \
          -H "x-api-key: YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{"transaction": {"type": "paid", "amount": 150, "currency": "USD"}}'
        ```
      </Tab>

      <Tab value="Node.js">
        ```javascript title="Node.js"
        const res = await fetch('https://api.chargeflow.io/public/2025-04-01/disputes/DISPUTE_ID', {
          method: 'PATCH',
          headers: {
            'x-api-key': process.env.CHARGEFLOW_API_KEY,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ transaction: { type: 'paid', amount: 150, currency: 'USD' } }),
        });
        const data = await res.json();
        ```
      </Tab>

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

        res = requests.patch(
            "https://api.chargeflow.io/public/2025-04-01/disputes/DISPUTE_ID",
            headers={"x-api-key": os.environ["CHARGEFLOW_API_KEY"]},
            json={"transaction": {"type": "paid", "amount": 150, "currency": "USD"}},
        )
        data = res.json()
        ```
      </Tab>
    </Tabs>

    Replace `DISPUTE_ID` with the `id` value from your dispute list.

    <Callout title="Note">
      Chargeflow's Enrichment Engine evaluates submitted artifacts and includes only those that
      strengthen the rebuttal - submit everything you have.
    </Callout>
  </Step>

  <Step>
    ## Register a webhook [#register-a-webhook]

    Subscribe to the `dispute.created` event to receive real-time notifications whenever a new dispute is ingested:

    <Tabs items="['curl', 'Node.js', 'Python']">
      <Tab value="curl">
        ```bash title="Terminal"
        curl -X POST https://api.chargeflow.io/public/2025-04-01/webhooks \
          -H "x-api-key: YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{"event": "dispute.created", "url": "https://your-server.com/webhook"}'
        ```
      </Tab>

      <Tab value="Node.js">
        ```javascript title="Node.js"
        const res = await fetch('https://api.chargeflow.io/public/2025-04-01/webhooks', {
          method: 'POST',
          headers: {
            'x-api-key': process.env.CHARGEFLOW_API_KEY,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ event: 'dispute.created', url: 'https://your-server.com/webhook' }),
        });
        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/webhooks",
            headers={"x-api-key": os.environ["CHARGEFLOW_API_KEY"]},
            json={"event": "dispute.created", "url": "https://your-server.com/webhook"},
        )
        data = res.json()
        ```
      </Tab>
    </Tabs>

    Each registration subscribes one endpoint to one event; repeat per event, or pass `"event": "*"` to receive all events.

    Chargeflow will send an HTTP POST to your endpoint each time a matching event occurs. Respond with `200` to acknowledge delivery.
  </Step>
</Steps>

## Next steps [#next-steps]

<Cards>
  <Card className="cf-card-outline" iconName="card-chip-1" title="Webhooks" href="/docs/reference/concepts/webhooks">
    Learn how to handle and verify webhook events in your server.
  </Card>

  <Card className="cf-card-outline" iconName="card-add-layer" title="Authentication" href="/docs/reference/api-fundamentals/authentication">
    Enable HMAC signature validation for production-grade security.
  </Card>

  <Card className="cf-card-outline" iconName="card-upload-file" title="Chargeback lifecycle" href="/docs/reference/concepts/chargeback-lifecycle">
    Understand dispute lifecycle, stages, and statuses.
  </Card>
</Cards>