You want complaints resolved before they post as chargebacks, with the alert data flowing through your own systems. This guide covers the Alerts API: choosing an integration model, the endpoints, and the outcome vocabulary. For the product overview, start at the Alerts landing page; the integration models are taught canonically in Alerts model.

How alerts work

Card networks issue a pre-chargeback alert when a cardholder questions a transaction, giving you a short window (typically 24-72 hours) to refund and stop the chargeback from posting. The end-to-end flow and the two integration models - Chargeflow Alerts (full automation) and merchant-managed (you issue the refund) - are covered in Alerts model. This guide is the API-level how-to: the endpoints, the webhooks, and the merchant-managed outcome flow.

Want the alerts delivered to your systems without Chargeflow touching the money? That is merchant-managed handling: you receive every alert over the API and webhooks, issue the refund (or decline) in your own processor, and report the result back. The steps below are what your side owns.

Available endpoints

Endpoint	Method	Description
`/public/2025-04-01/alerts`	GET	Retrieve a paginated list of all alerts for your account. Supports filtering by date, type, status, and reason.
`/public/2025-04-01/alerts/{id}`	GET	Retrieve full details of a specific alert by its ID, including status, outcome, and transaction details.
`/public/2025-04-01/alerts/{id}/outcome`	POST	Update the outcome for a specific alert. Required when using Merchant-Managed Handling.

403 on the read endpoints?

Read access to the Alerts endpoints is enabled per account, and working webhook delivery does not grant it. If a key that passes the credential check (GET /health-check/access-key) still gets 403 here, ask Support to enable it.

Available webhooks

Webhook	Trigger	Description
`alerts.created`	A new pre-chargeback alert is received	Sends an HTTP POST to your endpoint with the alert ID and metadata. Use this to initiate refunds or other mitigation actions.
`alerts.transaction.linked`	Chargeflow matches an alert to a transaction	Sends an HTTP POST with the alert ID and matched transaction ID. Useful if you need transaction-level data for your automated processes.
`alerts.updated`	The outcome of an alert is updated	Sends an HTTP POST with the updated outcome and timestamp.

Merchant-Managed: step-by-step responsibilities

If you are using the Merchant-Managed model, your system must complete the following steps for each alert:

Receive the alert

Listen for alerts.created on your webhook endpoint. The payload includes the alert ID and metadata. If you need the matched PSP transaction ID before taking action, also subscribe to alerts.transaction.linked.

Locate and validate the transaction

Using the alert metadata (amount, currency, card details, ARN), find the corresponding transaction in your payment processor or order management system.

Issue the refund

Process the refund in your payment processor. Keep a record of the refund confirmation.

Report the outcome to Chargeflow

Call POST /public/2025-04-01/alerts/{id}/outcome with the result. This step is critical: without it, Chargeflow cannot report back to the issuer and the chargeback may still be filed.

Terminal

curl -X POST https://api.chargeflow.io/public/2025-04-01/alerts/ALERT_ID/outcome \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "refunded"}'

Warning

Failing to call the outcome endpoint in Merchant-Managed mode means Chargeflow cannot close the alert with the issuer. Always report outcomes, even if the transaction was already refunded (previously_refunded).

Alert outcomes

Alert outcomes use a single vocabulary. The same six values apply to the value you post to POST /alerts/{id}/outcome and the value you receive on the alerts.updated webhook. Until an alert reaches a final outcome, outcome reads as null.

Value	Meaning
`refunded`	The transaction was refunded successfully.
`previously_refunded`	The transaction had already been refunded before the alert arrived.
`duplicate`	The alert duplicates one that was already handled.
`decline`	The refund request was declined, no refund was issued.
`error`	A general error occurred while handling the alert.
`transaction_not_found`	No matching transaction could be found to process a refund.