canonical: https://jentic.com/apis/chargeblast.io/chargeblast-io

# Chargeblast API

Chargeblast is a chargeback alert and prevention tool that notifies merchants whenever a cardholder initiates a dispute, allowing the merchant to refund or contest before it becomes a chargeback. This domain hosts an expanded set of v2 and v3 endpoints covering alert tracking, order ingestion, credit requests, deflection logs, and merchant enrollment. It is targeted at merchants and processors operating in card-not-present commerce who need to drive chargeback ratios down quickly.

## For AI agents

Track chargeback alerts, ingest orders for matching, request credits to deflect disputes, and manage merchant enrollment. Useful for fraud and dispute operations agents working across multiple alert generations.

## Scope

Does not handle payment authorisation, refund settlement on the acquirer side, or representment of already-posted chargebacks - use for pre-dispute alert deflection, order matching, and merchant enrollment only.

## Capabilities

- Pull deflection logs from `/api/v3/deflections/logs` to audit which alerts were resolved before posting
- Track outbound notifications and webhook callbacks via POST `/api/v2/track`
- Manage order data with GET `/api/v2/orders`, individual lookups, and POST `/api/v2/orders/upload` bulk ingestion
- List, retrieve, and update chargeback alerts via `/api/alerts` and `/api/v2/alerts` plus the alert/{id} variants
- Submit credit requests with POST `/api/v2/credit-request/create` to deflect alerts before they convert
- Enroll and unenroll merchants in the alert network through `/api/enroll_merchant` and `/api/unenroll`
- Read the descriptor and merchant catalog with `/api/descriptors` and `/api/merchant`

## Use cases

### Multi-Network Chargeback Deflection

Merchants enrolled across CDRN, Ethoca, and RDR pull alerts from `/api/v2/alerts` and decide whether to refund (deflect) or fight. The platform lets the merchant call POST `/api/v2/credit-request/create` to instruct the issuer to credit the cardholder, which prevents the dispute from progressing into a chargeback. Audit trails are pulled from `/api/v3/deflections/logs.`

Example prompt: Pull `/api/v2/alerts` with state=open, post `/api/v2/credit-request/create` for each over the deflection threshold, then verify with `/api/v3/deflections/logs`

### Order Sync for Faster Resolution

POST `/api/v2/orders/upload` accepts a batch of completed orders so incoming alerts can be matched against the merchant's actual transaction record. Better matching reduces manual review time on the dispute desk and lets the merchant decide on credit-vs-fight in seconds rather than minutes.

Example prompt: POST `/api/v2/orders/upload` with the last 24 hours of orders and confirm via GET `/api/v2/orders` that the records are searchable

### Merchant Onboarding into Alert Networks

Payment service providers and aggregators onboard merchants into the chargeback alert networks through POST `/api/enroll_merchant.` The endpoint registers the descriptors and the merchant identifier; POST `/api/unenroll` cleanly reverses enrollment when the merchant offboards. GET `/api/merchants` and `/api/descriptors` give the read-side view for reconciliation.

Example prompt: POST `/api/enroll_merchant` with merchant identifiers and descriptors, then verify via GET `/api/merchants`

### Agent-Driven Dispute Operations via Jentic

An AI agent given a directive like 'deflect any open alert under $200 by issuing a credit' can resolve the workflow through Jentic. The agent searches Jentic for the list-alerts and credit-request operations, iterates the alerts, and issues the credit instructions, while the API key stays in your Jentic One instance.

Example prompt: Search Jentic for 'list chargeback alerts', filter to open alerts under $200, and post `/api/v2/credit-request/create` for each

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v2/alerts` | List chargeback alerts (v2) |
| POST | `/api/v2/alerts/update/{id}` | Update an alert outcome (v2) |
| POST | `/api/v2/credit-request/create` | Submit a credit request to deflect an alert |
| POST | `/api/v2/orders/upload` | Bulk upload merchant orders |
| GET | `/api/v2/orders/{id}` | Retrieve a single order by ID |
| GET | `/api/v3/deflections/logs` | Read deflection audit logs (v3) |
| POST | `/api/enroll_merchant` | Enroll a merchant into the alert network |

## Key resources

- **Alerts** — Pre-dispute notifications across v1 and v2 endpoints with detail and update operations
- **Orders** — Merchant order records uploaded for matching against incoming alerts
- **Credit Requests** — Refund instructions submitted to deflect alerts before they post as chargebacks
- **Deflection Logs** — Audit trail of resolved alerts under the v3 deflections namespace
- **Merchants and Descriptors** — Enrolled merchant identifiers and the card descriptors covered by the alert network

## Why Jentic

- **Setup:** Wiring Chargeblast by hand means learning its X-API-Key header auth and attaching the key to every alert, order, and enrollment call yourself. Through Jentic you install once, import Chargeblast from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Chargeblast puts the alert and order ids in the URL path (`/api/v2/alerts/update/{id}`, `/api/v2/orders/{id}`), so a rule can pin your agent to a given alert or order and nothing else. You choose the operations it may call, so merchant enrollment or credit-request creation are not included unless you add them.
- **Credential handling:** Your Chargeblast 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 alerts' or 'submit a credit request', and Jentic returns the matching Chargeblast operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Chargeflow API** — Chargeflow automates representment for posted chargebacks; Chargeblast focuses on deflecting them in the pre-dispute window.
- **Sift API** — Sift scores transactions for fraud risk before authorisation; Chargeblast handles the post-auth dispute lifecycle.
- **Stripe API** — Stripe is the payment processor; Chargeblast operates on the disputes those Stripe charges generate.

## FAQ

### What authentication does the Chargeblast API use?

Chargeblast uses an API key in the X-API-Key header on every request. Through Jentic, the key is stored encrypted in your Jentic One instance and only injected server-side at execution time.

### Can I deflect a chargeback by issuing a credit through the Chargeblast API?

Yes. POST `/api/v2/credit-request/create` with the alert ID and credit amount and Chargeblast forwards the credit instruction to the issuer. If accepted in time, the dispute is closed before it becomes a chargeback.

### What is the difference between the v2 and v3 endpoints on this API?

The v2 endpoints handle alert listing, order upload, and credit-request creation. The v3 namespace currently exposes `/api/v3/deflections/logs` for the audit trail. Both versions share the same X-API-Key auth and base URL.

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

Chargeblast does not publish a fixed public rate limit. Real-time alert workloads should poll `/api/v2/alerts` at modest intervals and bulk-upload orders via `/api/v2/orders/upload` rather than per-order writes; back off on HTTP 429.

### How do I bulk-upload orders for matching through Jentic?

Install jentic with pip install jentic, search for 'upload merchant orders for chargeback matching', load the schema for POST `/api/v2/orders/upload`, and execute. Run Jentic One, the self-hosted execution layer, for an agent API key.

### Does the Chargeblast API expose deflection audit logs?

Yes. GET `/api/v3/deflections/logs` returns the history of alerts that were successfully deflected, suitable for compliance reporting and reconciliation against the merchant's chargeback ratio over time.

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

Yes. Because you run Jentic One yourself, your own rules decide which Chargeblast operations and credentials the agent may use. Since Chargeblast puts the alert and order ids in the URL path, such as `/api/v2/alerts/update/{id}` and `/api/v2/orders/{id}`, you can pin the agent to a specific alert or order and nothing else. You pick the operations it may call, so merchant enrollment via `/api/enroll_merchant` or credit-request creation via `/api/v2/credit-request/create` stay off limits unless you add them.