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

# Chargeblast API

Chargeblast is a chargeback prevention platform that lets merchants enroll their card descriptors into pre-dispute alert networks (Verifi CDRN, Ethoca, RDR), receive alerts when a cardholder initiates a dispute, and resolve them with a refund or representment before they become a chargeback. The v2 API exposes alerts, merchant enrollment, descriptor management, deflection logs, credit requests, and order data uploads. It is intended for risk teams, payment processors, and high-risk merchants who need to act on disputes within minutes of cardholder action.

## For AI agents

Read pre-dispute chargeback alerts, manage descriptor enrollments, upload order data for matching, and issue credit requests to deflect chargebacks before they post. Useful for fraud and dispute operations agents.

## Scope

Does not handle payment authorisation, refund settlement, or representment of posted chargebacks - use for pre-dispute alert deflection and descriptor enrollment only.

## Capabilities

- List incoming chargeback alerts with `/api/v2/alerts` and pull a single alert detail by ID
- Update an alert's outcome (refund, representment, decline) via PUT `/api/v2/alerts/{id}/update`
- Enroll and unenroll merchants and their card descriptors into the alert network through `/api/enroll_merchant` and `/api/unenroll_merchant`
- List the descriptors and merchants currently registered against the account for reconciliation
- Push order metadata in bulk with POST `/api/upload_orders` so alerts can be matched back to the originating transaction
- Submit a credit request for a flagged transaction via POST `/api/credit_requests` to deflect the dispute
- Pull deflection logs to verify that submitted credits successfully prevented chargebacks

## Use cases

### Real-Time Chargeback Deflection

Risk operations teams poll `/api/v2/alerts` for new pre-dispute notifications coming from CDRN, Ethoca, and RDR networks. When an alert matches an order they want to refund rather than dispute, they call POST `/api/credit_requests` within minutes, which Chargeblast forwards to the issuer and which prevents the dispute from becoming a chargeback. Deflection cost is far lower than the chargeback fee plus lost goods.

Example prompt: List `/api/v2/alerts` with state=open, match each to a recent order, and POST `/api/credit_requests` for any over the deflection threshold

### Descriptor and Merchant Onboarding

Payment processors and merchant aggregators onboard new descriptors into the chargeback alert networks through POST `/api/enroll_merchant.` Each enrolled descriptor begins receiving alerts when issuers flag transactions, and unenrolling via POST `/api/unenroll_merchant` cleanly removes coverage when a merchant offboards. The `/api/merchants` and `/api/descriptors` endpoints provide the read side for reconciliation.

Example prompt: POST `/api/enroll_merchant` for a new merchant with their MID and descriptors, then GET `/api/merchants` to verify enrollment status

### Order Data Matching

Pre-dispute alerts arrive with cardholder details but limited transaction context, so merchants upload order metadata via POST `/api/upload_orders` so Chargeblast can match alerts back to the originating order. Better matching means faster resolution decisions and clearer refund evidence. Bulk uploads run nightly or on order completion.

Example prompt: POST `/api/upload_orders` with the last 24 hours of completed orders so subsequent alerts can be matched automatically

### Agent-Managed Dispute Operations via Jentic

An AI agent given a directive like 'refund any open chargeback alerts over $50' can resolve the workflow through Jentic. The agent searches for the list-alerts and credit-requests operations, iterates the open alerts, and issues credit requests against ones that meet the rule, all without holding the API key.

Example prompt: Search Jentic for 'list chargeback alerts', filter to open alerts over $50, and post credit requests for each

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v2/alerts` | List chargeback alerts |
| GET | `/api/v2/alerts/{id}` | Retrieve a single alert by ID |
| PUT | `/api/v2/alerts/{id}/update` | Update an alert outcome |
| POST | `/api/enroll_merchant` | Enroll a merchant descriptor in the alert network |
| POST | `/api/credit_requests` | Submit a credit request to deflect an alert |
| POST | `/api/upload_orders` | Bulk upload order metadata for matching |
| GET | `/api/deflection_logs` | Audit log of deflected alerts |

## Key resources

- **Alerts** — Pre-dispute notifications from CDRN, Ethoca, and RDR networks with cardholder and transaction context
- **Merchants and Descriptors** — Merchant accounts and their card descriptors enrolled in the alert network
- **Credit Requests** — Submitted refund instructions used to deflect alerts before they become chargebacks
- **Orders** — Order metadata uploaded for matching against incoming alerts
- **Deflection Logs** — Audit trail of which alerts were successfully deflected

## Why Jentic

- **Setup:** Wiring Chargeblast by hand means learning its X-API-Key header auth and attaching the key to every alert 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 id in the URL path (`/api/v2/alerts/{id}/...`), so a rule can pin your agent to reading and updating a given alert and nothing else. You choose the operations it may call, so merchant enrollment or credit requests 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 chargeback representment and evidence; Chargeblast focuses on pre-dispute alert deflection.
- **Sift API** — Sift scores transactions for fraud risk before authorisation; Chargeblast deflects post-authorisation disputes.
- **Stripe API** — Stripe is the underlying payment processor that funds the credits Chargeblast instructs you to issue.

## FAQ

### What authentication does the Chargeblast API use?

Chargeblast uses an API key passed in the X-API-Key header on every request. Through Jentic, the key stays encrypted in your Jentic One instance and the agent receives a scoped execution token instead of the raw secret.

### Can I deflect a chargeback alert before it becomes a chargeback with the Chargeblast API?

Yes. POST `/api/credit_requests` against the alert ID with the credit amount and Chargeblast forwards the credit instruction to the issuer through the alert network. If accepted in time, the dispute does not progress to a chargeback.

### How do I match alerts to my own order records?

Bulk-upload order metadata to POST `/api/upload_orders` so Chargeblast can match incoming alerts by descriptor, amount, and date. Orders with richer matching data resolve faster and reduce manual review time.

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

Chargeblast does not publish a fixed public rate limit. As a real-time alert API, it favours short polling on `/api/v2/alerts` and bulk uploads on `/api/upload_orders` rather than high-frequency individual writes; back off on HTTP 429 responses.

### How do I list open chargeback alerts through Jentic?

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

### Does the Chargeblast API support enrolling descriptors into both Verifi and Ethoca networks?

Yes. POST `/api/enroll_merchant` accepts the merchant identifiers and descriptors and Chargeblast handles enrollment into the supported pre-dispute networks (CDRN, Ethoca, RDR) on the back end. GET `/api/descriptors` confirms what is currently registered.

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

Yes. Jentic One runs self-hosted, so your own rules decide which Chargeblast operations and credentials the agent may use. Because Chargeblast puts the alert id in the URL path (`/api/v2/alerts/{id}/update`), you can pin the agent to reading and updating a specific alert and nothing else. Merchant enrollment via POST `/api/enroll_merchant` and credit requests via POST `/api/credit_requests` stay out of reach unless you explicitly grant them.