# FAQ (https://docs.chargeflow.io/docs/reference/faq)



You are evaluating or integrating Chargeflow and need a quick answer - on the API, security, data handling, or how Chargeflow operates. Each answer here is short by design and links to the page where the topic is documented in full.

## Getting started [#getting-started]

<Accordions type="single">
  <Accordion title="What platform do I need to connect to use the API?">
    Any of them. The API is platform-independent: it reads and writes the disputes and alerts already ingested into your account, so all that matters is that at least one payment processor or store is connected. See [Integrations & Ecosystem](https://docs.chargeflow.io/docs/reference/integrations).
  </Accordion>

  <Accordion title="I generated an API key - what do I do with it?">
    Send it as the `x-api-key` header on requests to `https://api.chargeflow.io`. Validate it first against the key health check, then list your disputes: both calls are copy-paste ready in the [Quickstart](https://docs.chargeflow.io/docs/merchants/quickstart).
  </Accordion>

  <Accordion title="Does my plan affect API access, or does someone have to approve it?">
    Neither. Any active Chargeflow account can generate a key under **Settings → Developers**, with no plan requirement and no approval step. Read access to the Alerts and Disputes endpoints is the one exception: it is enabled per account, so if a valid key returns `403` on those, ask [Support](https://docs.chargeflow.io/docs/reference/support) to enable it.
  </Accordion>

  <Accordion title="Can I pull my dispute data into an AI tool like Claude or ChatGPT?">
    Yes, and the path we recommend is Zapier MCP rather than a hand-written API script: it connects Chargeflow to AI tools without any authentication or signing code of your own to maintain. Set the Chargeflow connection up once as described in [Zapier integration (no-code)](https://docs.chargeflow.io/docs/merchants/automation/zapier-no-code#connect-chargeflow-to-an-ai-assistant). A first-party Chargeflow MCP server is on the way, see [Tools](https://docs.chargeflow.io/docs/reference/tools#mcp-server).
  </Accordion>
</Accordions>

## Authentication [#authentication]

<Accordions type="single">
  <Accordion title="How do I authenticate API requests?">
    Chargeflow uses API key authentication. Include your API Access Key in the `x-api-key` header on every request. See [Authentication](https://docs.chargeflow.io/docs/reference/api-fundamentals/authentication).
  </Accordion>

  <Accordion title="Where do I get my API keys?">
    Generate your keys in the Chargeflow app under **Settings → Developers → Generate Keys**. Your API Secret Key is shown only once, so store it securely. See [Authentication](https://docs.chargeflow.io/docs/reference/api-fundamentals/authentication).
  </Accordion>

  <Accordion title="What is the API key for? Is it only for webhooks?">
    It does both jobs. The Access Key authenticates every REST call you make, and generating it is also what unlocks webhook registration: the Secret Key that pairs with it is used to sign webhook deliveries so you can verify them. See [Authentication](https://docs.chargeflow.io/docs/reference/api-fundamentals/authentication) and [Webhooks](https://docs.chargeflow.io/docs/reference/concepts/webhooks).
  </Accordion>

  <Accordion title="Where do I enter the API key - in my CRM or in my PSP portal?">
    Neither: the key belongs wherever your own code or automation calls Chargeflow, for example your backend, a Zapier connection, or your CRM's outbound HTTP step. Never paste it into your payment processor's portal, and never expose it in client-side code. See [Authentication](https://docs.chargeflow.io/docs/reference/api-fundamentals/authentication).
  </Accordion>

  <Accordion title="What is HMAC signature validation and do I need it?">
    HMAC signature validation is an optional second layer of security that proves your requests are authentic and untampered. It is disabled by default on new keys. When enabled, you send a signature in the `x-chargeflow-hmac-sha256` header. See [Authentication](https://docs.chargeflow.io/docs/reference/api-fundamentals/authentication).
  </Accordion>
</Accordions>

## Environments [#environments]

<Accordions type="single">
  <Accordion title="Is there a test or sandbox environment?">
    A fully isolated sandbox environment is planned but not yet available - see [Sandbox](https://docs.chargeflow.io/docs/merchants/sandbox) for current status; until then API keys act on your live account (see [Test credentials](https://docs.chargeflow.io/docs/reference/api-fundamentals/test-credentials)). When you go to production, follow the [go-live checklist](https://docs.chargeflow.io/docs/reference/api-fundamentals/go-live-checklist).
  </Accordion>

  <Accordion title="What base URL should I call?">
    All requests go to `https://api.chargeflow.io`, with the API version in the path, for example `https://api.chargeflow.io/public/2025-04-01/disputes`. See [API Versioning](https://docs.chargeflow.io/docs/reference/concepts/api-versioning).
  </Accordion>

  <Accordion title="Am I rate limited?">
    Per-plan rate limits are not published yet - see [Rate limits](https://docs.chargeflow.io/docs/reference/api-fundamentals/rate-limits) for status. If you receive a `429`, back off and retry; the retry pattern is in [Error handling](https://docs.chargeflow.io/docs/reference/api-fundamentals/error-handling).
  </Accordion>

  <Accordion title="Can I safely retry a failed request?">
    Reads (GET) are always safe to retry. For writes, full idempotency semantics are not published yet - see [Idempotency](https://docs.chargeflow.io/docs/reference/api-fundamentals/idempotency) for status and [Error handling](https://docs.chargeflow.io/docs/reference/api-fundamentals/error-handling) for which status codes are retry-safe.
  </Accordion>
</Accordions>

## Errors [#errors]

<Accordions type="single">
  <Accordion title="Why do I get 403 Forbidden on every endpoint, including the health check? Is my API access disabled?">
    It is almost certainly the request, not the account. A `403` (rather than a `401`) means the key was recognized but the request was rejected, and when even the health check returns it the usual cause is an HMAC signature or header that does not match the required `METHOD\nPATH\nBODY` format exactly. There is no "enable API access" switch for support to flip. See [Error handling](https://docs.chargeflow.io/docs/reference/api-fundamentals/error-handling) and the signing rules in [Authentication](https://docs.chargeflow.io/docs/reference/api-fundamentals/authentication).
  </Accordion>

  <Accordion title="Why do I get 'Missing API Key header x-api-key' when my key has not changed?">
    Because the header is not arriving. Nothing changed on the Chargeflow side: check that your client sends the header spelled exactly `x-api-key`, that it is set on the request that actually goes out (proxies and HTTP libraries sometimes drop unknown headers), and that it carries the Access Key rather than the Secret Key. See [Authentication](https://docs.chargeflow.io/docs/reference/api-fundamentals/authentication).
  </Accordion>

  <Accordion title="My key is valid but I cannot list alerts or disputes - is that an access-level restriction?">
    Yes. Read access to the Alerts and Disputes endpoints is enabled per account and is not granted automatically just because webhooks are working. If the [health check](https://docs.chargeflow.io/docs/reference/api-fundamentals/error-handling#health-check-endpoint) returns `200` and those endpoints still return `403`, ask [Support](https://docs.chargeflow.io/docs/reference/support) to enable read access on your account.
  </Accordion>
</Accordions>

## Webhooks [#webhooks]

<Accordions type="single">
  <Accordion title="How do I set up webhooks?">
    Register an HTTP endpoint in the Chargeflow app under **Settings → Developers → + Add Webhook**, then subscribe to the events you need. See [Webhooks](https://docs.chargeflow.io/docs/reference/concepts/webhooks).
  </Accordion>

  <Accordion title="What URL do I use for the webhook?">
    Your own. Chargeflow does not hand you a URL to call: you supply an HTTPS endpoint on your side that accepts `POST` requests and returns `2XX`, and Chargeflow delivers events to it. Register that URL under **Settings → Developers → + Add Webhook**. The handler code is in [Webhooks](https://docs.chargeflow.io/docs/reference/concepts/webhooks#configuring-webhooks).
  </Accordion>

  <Accordion title="Is there a webhook for when a dispute is updated, not just created?">
    No. `dispute.created` is the only dispute event today, fired when a dispute is first detected. Status changes, evidence submission, and outcomes are not pushed: poll `GET /public/2025-04-01/disputes/{disputeId}` or check the dashboard. Wider dispute-event coverage is on the roadmap. See [Merchant webhook events](https://docs.chargeflow.io/docs/merchants/webhook-events).
  </Accordion>

  <Accordion title="How do I verify that a webhook came from Chargeflow?">
    Each webhook POST includes an HMAC signature in the `X-Chargeflow-Hmac-Sha256` header. Recompute the signature from the request method, path, and body using your secret key and compare. See [Webhooks](https://docs.chargeflow.io/docs/reference/concepts/webhooks).
  </Accordion>

  <Accordion title="What should my endpoint return?">
    Return a `2XX` status code (preferably `200`) quickly to acknowledge receipt. If Chargeflow receives any other response, it retries delivery until a `2XX` is returned or the retry limit is reached. See [Webhooks](https://docs.chargeflow.io/docs/reference/concepts/webhooks).
  </Accordion>
</Accordions>

## Disputes [#disputes]

<Accordions type="single">
  <Accordion title="Where do disputes come from?">
    Disputes are ingested from your connected payment processors and platforms. Each dispute carries a `source` that identifies its origin, such as `stripe`, `paypal`, or `shopify_payments`. See [Integrations & Ecosystem](https://docs.chargeflow.io/docs/reference/integrations) and the [Disputes API](https://docs.chargeflow.io/docs/api/2025-04-01/merchants/disputes).
  </Accordion>

  <Accordion title="How do I know when a new dispute is created?">
    Subscribe to the `dispute.created` webhook event. See [Webhooks](https://docs.chargeflow.io/docs/reference/concepts/webhooks) and the [dispute.created event](https://docs.chargeflow.io/docs/merchants/webhook-events#dispute-created).
  </Accordion>

  <Accordion title="How do I add evidence or order data to a dispute?">
    Use the enrichment endpoints to attach order, transaction, and customer data. See [Enrich a dispute](https://docs.chargeflow.io/docs/merchants/automation/enrich-a-dispute) and [Upload evidence](https://docs.chargeflow.io/docs/merchants/automation/upload-evidence).
  </Accordion>

  <Accordion title="Will data I do not send still be used in the dispute response?">
    Only if Chargeflow can already see it. The response is built from what your connected integrations return plus whatever you send through the enrichment endpoints, so a field you never share cannot appear in the evidence. Also note that arrays you send replace the stored array rather than appending to it, so omitting an existing item removes it. See [Enrich a dispute](https://docs.chargeflow.io/docs/merchants/automation/enrich-a-dispute#important-array-merge-behavior).
  </Accordion>

  <Accordion title="I enriched a dispute via API - where do I confirm it landed?">
    Two places: the `PATCH` call returns the updated dispute object with your data merged in, and the same data appears on the dispute in the Chargeflow dashboard. If you need to re-read it later, call `GET /public/2025-04-01/disputes/{disputeId}`. See [Enrich a dispute](https://docs.chargeflow.io/docs/merchants/automation/enrich-a-dispute#response).
  </Accordion>
</Accordions>

## Alerts [#alerts]

<Accordions type="single">
  <Accordion title="What is a pre-chargeback alert?">
    A pre-chargeback alert is an early notification from a card network that a cardholder has disputed a transaction, giving you a short window to resolve it before it becomes a chargeback. See [Alerts model](https://docs.chargeflow.io/docs/reference/concepts/alerts-model).
  </Accordion>

  <Accordion title="Does Chargeflow resolve alerts for me?">
    It depends on the integration model. In the Chargeflow Alerts model, Chargeflow handles matching and refunds automatically. In the merchant-managed model, you perform the action and report the outcome. See [Manage pre-chargeback alerts](https://docs.chargeflow.io/docs/merchants/alerts/manage-alerts).
  </Accordion>

  <Accordion title="Can I receive alerts via API without Chargeflow processing the refund?">
    Yes, that is the merchant-managed model: Chargeflow delivers `alerts.created` (and `alerts.transaction.linked` once it matches a transaction), you issue the refund in your own processor, then report the result to `POST /public/2025-04-01/alerts/{id}/outcome`. Reporting the outcome is required, otherwise Chargeflow cannot close the alert with the issuer and the chargeback can still post. See [Manage pre-chargeback alerts](https://docs.chargeflow.io/docs/merchants/alerts/manage-alerts#merchant-managed-step-by-step-responsibilities).
  </Accordion>
</Accordions>

## Prevent [#prevent]

<Accordions type="single">
  <Accordion title="Does Prevent support an API or a custom integration?">
    Not yet. Prevent runs only through the [Chargeflow app for Shopify](https://apps.shopify.com/chargeflow) today: there is no public API and no custom integration path for other platforms, and no committed timeline for one. See [Prevent](https://docs.chargeflow.io/docs/merchants/prevent).
  </Accordion>
</Accordions>

## API versioning [#api-versioning]

<Accordions type="single">
  <Accordion title="How does versioning work?">
    Chargeflow uses date-based versioning in the request path, for example `2025-04-01`. Always include an explicit version so future changes do not affect your integration. See [API Versioning](https://docs.chargeflow.io/docs/reference/concepts/api-versioning).
  </Accordion>

  <Accordion title="Which version should I use?">
    Use the newest version in the [API Versioning](https://docs.chargeflow.io/docs/reference/concepts/api-versioning) version table for new integrations; that page also covers the deprecation policy.
  </Accordion>
</Accordions>

## Security & compliance [#security--compliance]

<Accordions type="single">
  <Accordion title="Is Chargeflow SOC 2 certified?">
    Yes, Chargeflow holds SOC 2 Type II certification. See [Security & compliance](https://docs.chargeflow.io/docs/reference/security) for the current certification list and roadmap.
  </Accordion>

  <Accordion title="Do you have a PCI attestation?">
    Generally not applicable - Chargeflow is not a cardholder-data environment and does not store full card numbers. The full rationale is in [Security & compliance](https://docs.chargeflow.io/docs/reference/security).
  </Accordion>

  <Accordion title="Where do I get the SOC 2 report, penetration test, or DPA?">
    All security and privacy documents are available through the [Chargeflow Trust Center](https://trust.chargeflow.io/), with gated reports granted on request. See [Security & compliance](https://docs.chargeflow.io/docs/reference/security).
  </Accordion>

  <Accordion title="Has Chargeflow had any security incidents?">
    Incident history is published in [Security & compliance](https://docs.chargeflow.io/docs/reference/security) and kept current at the [Trust Center](https://trust.chargeflow.io/).
  </Accordion>
</Accordions>

## Data & privacy [#data--privacy]

<Accordions type="single">
  <Accordion title="What customer data does Chargeflow store?">
    The data needed to automate disputes - encrypted in transit and at rest, and never full card numbers. The specifics are in [Security & compliance](https://docs.chargeflow.io/docs/reference/security).
  </Accordion>

  <Accordion title="Where is my data hosted, and do you support data residency?">
    Hosting, regions, and data-residency options are documented in [Security & compliance](https://docs.chargeflow.io/docs/reference/security).
  </Accordion>

  <Accordion title="How is a GDPR or data-subject request handled?">
    Chargeflow acts as a data processor on your behalf (you are the controller). Route data-subject requests through your account team or [support@chargeflow.io](mailto:support@chargeflow.io); the roles, transfer mechanisms, DPA, and privacy documentation are covered in [Security & compliance](https://docs.chargeflow.io/docs/reference/security) and the [Trust Center](https://trust.chargeflow.io/).
  </Accordion>

  <Accordion title="Do you use my data to train AI models?">
    No - see the AI governance section of [Security & compliance](https://docs.chargeflow.io/docs/reference/security).
  </Accordion>
</Accordions>

## How Chargeflow operates [#how-chargeflow-operates]

<Accordions type="single">
  <Accordion title="Does Chargeflow contact my customers directly?">
    It can. As part of resolving disputes at the earliest, lowest-cost stage, Chargeflow may reach out to end customers directly to resolve a case. The governing terms are in the [Terms of Service](https://www.chargeflow.io/terms-of-service).
  </Accordion>

  <Accordion title="Will you alert me if there is a problem with my integration, or is that my responsibility?">
    Both. Chargeflow monitors ingestion and integration health on its side, and you can poll the [health check endpoint](https://docs.chargeflow.io/docs/reference/api-fundamentals/error-handling) to confirm connectivity from yours. Maintaining the integration access Chargeflow relies on is the merchant's responsibility (see the [Terms of Service](https://www.chargeflow.io/terms-of-service)); if access breaks, disputes tied to it cannot be handled until it is restored.
  </Accordion>

  <Accordion title="How does billing and the deposit work?">
    Billing terms are set with your account team and depend on your plan. For specifics on fees, deposits, and charge timing, contact your account team or see the [Terms of Service](https://www.chargeflow.io/terms-of-service).
  </Accordion>
</Accordions>

## Next steps [#next-steps]

* Start with the [Quickstart](https://docs.chargeflow.io/docs/merchants/quickstart).
* Review the [go-live checklist](https://docs.chargeflow.io/docs/reference/api-fundamentals/go-live-checklist) before production.
* Still stuck? Contact [Support](https://docs.chargeflow.io/docs/reference/support).