Manage pre-chargeback alerts

The Alerts API: Chargeflow-automated versus merchant-managed handling, alert endpoints and webhooks, the refund-and-report flow, and outcome vocabularies.

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.

Available endpoints

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

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).

Outcome vocabularies

Alert outcomes use two distinct vocabularies. The value you post to the outcome endpoint is not the same set you receive on the alerts.updated webhook.

Outcome you POST to POST /alerts/{id}/outcome:

Value	Meaning
`refunded`	You refunded the transaction to handle the alert.
`previously_refunded`	The transaction had already been refunded before the alert arrived.
`duplicate`	The alert duplicates one you have already handled.
`decline`	You are declining to refund this alert.
`error`	You could not process the alert due to an error.

Outcome you RECEIVE on the alerts.updated webhook:

Value	Meaning
`duplicate`	The alert is a duplicate of an existing alert.
`not_found`	No matching transaction could be located.
`prevented`	The transaction was refunded and the chargeback was prevented.
`pending`	The alert is still being processed.
`chargebacked`	The alert escalated to a chargeback despite mitigation.
`previously_refunded`	The transaction was already refunded before the alert arrived.
`error`	An error occurred while handling the alert.

Next steps

Subscribe to Webhook EventsHow to register for alert webhooks.Webhook Events: alerts.createdPayload reference.Webhook Events: alerts.updatedPayload reference.Webhook Events: alerts.transaction.linkedPayload reference.

Manage pre-chargeback alerts

On this page