canonical: https://jentic.com/apis/chargeflow.io/chargeflow

# Chargeflow API

Chargeflow is an automated chargeback management platform that fights disputes on behalf of merchants by assembling evidence and submitting representment to issuers. The 2025-04-01 API exposes the full dispute lifecycle: pulling disputes and alerts, attaching evidence and order or subscription context, recording alert outcomes, capturing customer communication, managing webhooks, and handling data subject requests. It is built for e-commerce merchants and platforms that need to outsource chargeback representment without losing visibility into each case.

## For AI agents

Pull disputes and alerts, upload evidence and order context, record outcomes, manage webhooks, and process data subject requests on behalf of an e-commerce merchant. Useful for chargeback ops and platform finance agents.

## Scope

Does not handle payment authorisation, refund issuance through the acquirer, or fraud scoring of new transactions - use for chargeback dispute representment, evidence handling, and alert outcomes only.

## Capabilities

- List and inspect chargeback disputes through `/public/2025-04-01/disputes` and `/disputes/{disputeId}`, with PATCH to update fields
- Attach order, subscription, and free-form evidence to a dispute via the disputes/{disputeId}/evidence, /order, and /subscription sub-endpoints
- Pull pre-dispute alerts and post outcomes back through /alerts and `/alerts/{alertId}/outcome`
- Submit captured customer communication to support a representment case using POST /customer-communication
- Create and delete webhooks for real-time dispute and alert events via /webhooks endpoints
- Manage merchant accounts (create, list, retrieve, patch) for platforms that operate multiple Chargeflow tenants
- Process GDPR-style data subject removal requests with POST `/data-subject/removal` and check status by request ID

## Use cases

### Automated Chargeback Representment

Merchants pull each new chargeback via `/public/2025-04-01/disputes` and attach order details, subscription history, and customer communication so Chargeflow can compile a representment package and submit it to the issuer. Posting evidence through `/disputes/{disputeId}/evidence`, /order, and /subscription gives Chargeflow the structured signals it needs to build a winning case without merchant staff drafting documents manually.

Example prompt: GET `/public/2025-04-01/disputes` for new entries, then POST `/disputes/{disputeId}/order` with the matching order JSON for each

### Pre-Dispute Alert Resolution

Some Chargeflow accounts also receive pre-dispute alerts from networks like Verifi and Ethoca. The merchant pulls /alerts and `/alerts/{alertId}` for context and posts the resolution to `/alerts/{alertId}/outcome` - for example marking the alert as refunded - so the dispute does not progress to a chargeback.

Example prompt: List /alerts with status=open, fetch details for each, and POST `/alerts/{alertId}/outcome` with refund decisions where applicable

### Real-Time Dispute Webhooks

Risk and finance teams subscribe to dispute events through POST `/public/2025-04-01/webhooks` so an internal system reacts the moment a chargeback is opened, updated, or resolved. The webhook endpoint can be deleted via DELETE `/webhooks/{id}` when an integration is decommissioned, keeping the subscription list clean.

Example prompt: POST `/public/2025-04-01/webhooks` with the merchant's callback URL and the dispute.* event types, then GET /webhooks to verify

### Multi-Tenant Platform Operations via Jentic

Platforms that manage Chargeflow on behalf of sub-merchants use POST /accounts to provision tenants and PATCH `/accounts/{accountId}` to manage settings. An agent operating through Jentic can create new accounts, attach disputes, and pull dispute status across the entire tenant graph from a single intent - without ever holding the parent platform's API key directly.

Example prompt: Search Jentic for 'create chargeflow account', POST /accounts for the new tenant, then GET /disputes scoped to that account

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/public/2025-04-01/disputes` | List chargeback disputes |
| GET | `/public/2025-04-01/disputes/{disputeId}` | Retrieve a single dispute |
| POST | `/public/2025-04-01/disputes/{disputeId}/evidence` | Attach evidence to a dispute |
| POST | `/public/2025-04-01/disputes/{disputeId}/order` | Attach order context to a dispute |
| POST | `/public/2025-04-01/alerts/{alertId}/outcome` | Record an alert outcome |
| POST | `/public/2025-04-01/webhooks` | Subscribe to dispute and alert events |
| POST | `/public/2025-04-01/data-subject/removal` | Submit a data subject removal request |

## Key resources

- **Disputes** — Chargebacks under representment, with detail, patch, and evidence attachment operations
- **Alerts** — Pre-dispute alerts with detail and outcome posting
- **Evidence** — Standalone and dispute-attached evidence records uploaded for representment
- **Webhooks** — Real-time event subscriptions for dispute and alert lifecycle changes
- **Accounts** — Merchant tenants managed under a platform integration
- **Data Subject Requests** — Removal requests for cardholder data subject obligations

## Why Jentic

- **Setup:** Wiring Chargeflow by hand means learning its x-api-key header auth, tracking the dated public path prefix, and attaching the key to every dispute and evidence call yourself. Through Jentic you install once, import Chargeflow from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Chargeflow puts the dispute id in the URL path (`/public/2025-04-01/disputes/{disputeId}/...`), so a rule can pin your agent to one dispute: it can attach evidence and order data for that dispute and nothing else. You choose the operations it may call, so a data-subject removal is not included unless you add it.
- **Credential handling:** Your Chargeflow API key is stored once, encrypted, by your own Jentic One instance and injected into the x-api-key header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list chargeback disputes' or 'attach order data to a dispute', and Jentic returns the matching Chargeflow operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Chargeblast API** — Chargeblast focuses on pre-dispute alert deflection; Chargeflow specialises in representment of disputes that have already posted.
- **Sift API** — Sift scores transactions for fraud risk pre-authorisation; Chargeflow handles the post-auth chargeback lifecycle.
- **Stripe API** — Stripe is the payment processor whose disputes Chargeflow contests on the merchant's behalf.

## FAQ

### What authentication does the Chargeflow API use?

Chargeflow uses an API key passed in the x-api-key header on every request. You can validate the key against `/public/2025-04-01/health-check/access-key.` Through Jentic, the key stays encrypted in your Jentic One instance and is injected only at execution time.

### Can I attach order data to a dispute as evidence with the Chargeflow API?

Yes. POST `/public/2025-04-01/disputes/{disputeId}/order` with the structured order JSON, including line items, ship address, and tracking. The same dispute can also receive subscription context via /subscription and free-form evidence via /evidence.

### How do I subscribe to dispute events with the Chargeflow API?

Call POST `/public/2025-04-01/webhooks` with your callback URL and the event types you care about. List active subscriptions via GET `/public/2025-04-01/webhooks` and remove them with DELETE `/public/2025-04-01/webhooks/{id}` when no longer needed.

### What are the rate limits for the Chargeflow API?

Chargeflow does not publish a fixed public rate limit. Treat it as a workflow API: pull disputes on a schedule, batch evidence uploads where the API supports it, and back off on HTTP 429 responses.

### How do I list new chargeback disputes through Jentic?

Install jentic with pip install jentic, search for 'list chargeback disputes', load the schema for GET `/public/2025-04-01/disputes`, and execute. Run Jentic One, the self-hosted execution layer, to issue an agent API key.

### Does the Chargeflow API support multi-tenant platforms?

Yes. Use POST `/public/2025-04-01/accounts` to provision a sub-merchant account and PATCH `/public/2025-04-01/accounts/{accountId}` to update its settings. List managed tenants via GET `/public/2025-04-01/accounts.`

### Can I limit what my agent is allowed to do with the Chargeflow API?

Yes. Because you run Jentic One yourself, your own rules decide which Chargeflow operations and credentials the agent can use. Since Chargeflow puts the dispute id in the URL path, you can pin the agent to a single dispute so it only attaches evidence and order data for that case through POST `/disputes/{disputeId}/evidence` and /order. You pick the operations it may call, so a POST `/data-subject/removal` request is off-limits unless you explicitly allow it.