Alerts

List, retrieve, and action network alerts for accessible organisations.

Verifi RDR alerts are resolved automatically. Verifi RDR alerts arrive with status RESOLVED or INVALID and do not require actioning. The ACTION_REQUIRED status and the PATCH endpoint for actioning alerts apply to Ethoca alerts only.

Ethoca alerts in ACTION_REQUIRED status must be actioned. Refunding the transaction alone is not enough to prevent a chargeback. You must also action the alert using the PATCH endpoint so that Ethoca is notified and can stop the dispute. Unactioned alerts provide no value — the chargeback will proceed regardless of whether you refunded the customer. If you have resolution rules configured, matching alerts are resolved automatically. In rare cases, an alert may still appear as ACTION_REQUIRED if the system cannot match the alert to a transaction or cannot process the refund.

Base URL: https://api.chargebackstop.com/v1/alerts/

Authentication: Bearer token via API key.

Required abilities:

• alerts:read for GET endpoints

• alerts:write for PATCH endpoints

Access scope model:

• Organisation-level keys can access alerts for their own organisation only.

• Admin partner-group keys can access alerts across all organisations for their partner.

• Non-admin partner-group keys can access alerts only for organisations assigned to their group.

---

GET /v1/alerts - list alerts

Returns a paginated list of alerts accessible to the authenticated key.

API level: Organisation-level and partner-level Authentication: alerts:read

Query parameters

Parameter	Type	Description
status	string	Filter by alert status: ACTION_REQUIRED (Ethoca only), RESOLVED, INVALID
organisation_id	string	Filter by organisation ID
merchant_id	string	Filter by merchant ID
alert_received_at_gte	datetime	Include alerts received at or after this timestamp (ISO 8601, inclusive)
alert_received_at_lte	datetime	Include alerts received at or before this timestamp (ISO 8601, inclusive)
sort	string	Sort field: -alert_received_at (default), alert_received_at, -action_required_deadline, action_required_deadline
limit	integer	Number of results per page
offset	integer	Number of results to skip

Response codes

Code	Description
200	Success
400	Invalid request
401	Unauthorised
403	Forbidden — API key lacks alerts:read ability
422	Validation error (e.g. invalid date range)

Important behaviour

• If both alert_received_at_gte and alert_received_at_lte are sent, alert_received_at_gte must be less than or equal to alert_received_at_lte.

• Default sort order is newest alert received first (-alert_received_at).

Example 1 request

curl -X GET "https://api.chargebackstop.com/v1/alerts/?status=ACTION_REQUIRED&sort=-alert_received_at&limit=20&offset=0" \
  -H "Authorization: Bearer <api_key>"

Example 1 response

{
  "items": [
    {
      "id": "netalrt_abc123",
      "alert_network_id": "1234567890",
      "organisation_id": "org_xyz456",
      "merchant_id": "mrch_abc123",
      "enrolment_id": "enrl_def456",
      "enrolment_type": "ETHOCA_ALERT",
      "status": "ACTION_REQUIRED",
      "chargeback_reason_code": "10.4",
      "transaction_amount_in_cents": 4999,
      "transaction_currency_code": "USD",
      "transaction_authorised_at": "2026-02-10T10:30:00Z",
      "action_required_deadline": "2026-02-17T10:30:00Z",
      "transaction_authorisation_code": "ABC123",
      "transaction_acquirer_reference_number": "74027012345678901234567",
      "transaction_statement_descriptor": "EXAMPLE STORE",
      "transaction_card_bin": "424242",
      "transaction_card_last4": "4242",
      "transaction_card_scheme": "VISA",
      "transaction_card_issuer": "Example Bank",
      "transaction_refund_outcome": null,
      "transaction_network_id": null,
      "subscription_cancel_outcome": null,
      "note": "Customer requested immediate review",
      "created_at": "2026-02-11T10:30:00Z",
      "updated_at": "2026-02-11T10:30:00Z",
      "integration_id": null,
      "integration_transaction_id": null,
      "links": [
        {
          "rel": "self",
          "uri": "/v1/alerts/netalrt_abc123"
        }
      ]
    }
  ],
  "count": 1
}

---

GET /v1/alerts/{alert_id} - get alert by ID

Returns one alert if it is visible to the authenticated key.

API level: Organisation-level and partner-level Authentication: alerts:read

URL parameters

Parameter	Type	Description
alert_id	string	Alert ID

Response codes

Code	Description
200	Success
400	Invalid request
401	Unauthorised
403	Forbidden — API key lacks alerts:read ability
404	Alert not found

Important behaviour

• The same eligibility rules as list alerts apply.

• Non-existent alerts return 404 Not found.

Example 2 request

curl -X GET "https://api.chargebackstop.com/v1/alerts/netalrt_abc123" \
  -H "Authorization: Bearer <api_key>"

Example 2 response

{
  "id": "netalrt_abc123",
  "alert_network_id": "1234567890",
  "organisation_id": "org_xyz456",
  "merchant_id": "mrch_abc123",
  "enrolment_id": "enrl_def456",
  "enrolment_type": "ETHOCA_ALERT",
  "status": "ACTION_REQUIRED",
  "chargeback_reason_code": "10.4",
  "transaction_amount_in_cents": 4999,
  "transaction_currency_code": "USD",
  "transaction_authorised_at": "2026-02-10T10:30:00Z",
  "action_required_deadline": "2026-02-17T10:30:00Z",
  "transaction_authorisation_code": "ABC123",
  "transaction_acquirer_reference_number": "74027012345678901234567",
  "transaction_statement_descriptor": "EXAMPLE STORE",
  "transaction_card_bin": "424242",
  "transaction_card_last4": "4242",
  "transaction_card_scheme": "VISA",
  "transaction_card_issuer": "Example Bank",
  "transaction_refund_outcome": null,
  "transaction_network_id": null,
  "subscription_cancel_outcome": null,
  "note": "Customer requested immediate review",
  "created_at": "2026-02-11T10:30:00Z",
  "updated_at": "2026-02-11T10:30:00Z",
  "integration_id": null,
  "integration_transaction_id": null,
  "links": [
    {
      "rel": "self",
      "uri": "/v1/alerts/netalrt_abc123"
    }
  ]
}

---

PATCH /v1/alerts/{alert_id} - update alert

Updates the alert note and/or actions the alert.

API level: Organisation-level and partner-level Authentication: alerts:write

URL parameters

Parameter	Type	Description
alert_id	string	Alert ID to update

Request body

All fields are optional.

Field	Type	Required	Description
action	string	No	Action to apply: REFUND, CANCEL, REFUND_AND_CANCEL, ACCEPT_DISPUTE
note	string	No	Customer-facing note saved on the alert

Response codes

Code	Description
200	Success
400	Invalid request
401	Unauthorised
403	Forbidden — API key lacks alerts:write ability
404	Alert not found
422	Validation error (e.g. invalid action, alert already resolved)

Important behaviour

• This endpoint applies to Ethoca alerts only. Verifi RDR alerts are resolved automatically and cannot be actioned.

• If note is provided, it is saved on the alert.

• If action is omitted, only the note is updated.

• Once an alert is in RESOLVED, it cannot be actioned again.

• Action values map to available underlying actions at runtime. For detailed behaviour, see Actioning alerts:

  • REFUND prioritises refund actions.

  • CANCEL prioritises cancel/dismiss actions.

  • REFUND_AND_CANCEL prioritises combined refund-and-cancel, then refund-only if combined action is unavailable.

  • ACCEPT_DISPUTE maps to dismissing the alert.

Example 3 request

curl -X PATCH "https://api.chargebackstop.com/v1/alerts/netalrt_abc123" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "ACCEPT_DISPUTE",
    "note": "We decided to accept this dispute"
  }'

Example 3 response

{
  "id": "netalrt_abc123",
  "alert_network_id": "1234567890",
  "organisation_id": "org_xyz456",
  "merchant_id": "mrch_abc123",
  "enrolment_id": "enrl_def456",
  "enrolment_type": "ETHOCA_ALERT",
  "status": "RESOLVED",
  "chargeback_reason_code": "10.4",
  "transaction_amount_in_cents": 4999,
  "transaction_currency_code": "USD",
  "transaction_authorised_at": "2026-02-10T10:30:00Z",
  "action_required_deadline": "2026-02-17T10:30:00Z",
  "transaction_authorisation_code": "ABC123",
  "transaction_acquirer_reference_number": "74027012345678901234567",
  "transaction_statement_descriptor": "EXAMPLE STORE",
  "transaction_card_bin": "424242",
  "transaction_card_last4": "4242",
  "transaction_card_scheme": "VISA",
  "transaction_card_issuer": "Example Bank",
  "transaction_refund_outcome": "NOT_REFUNDED",
  "transaction_network_id": null,
  "subscription_cancel_outcome": null,
  "note": "We decided to accept this dispute",
  "created_at": "2026-02-11T10:30:00Z",
  "updated_at": "2026-02-11T10:32:00Z",
  "integration_id": null,
  "integration_transaction_id": null,
  "links": [
    {
      "rel": "self",
      "uri": "/v1/alerts/netalrt_abc123"
    }
  ]
}

---

Common error responses

Error responses use this shape:

{
  "errors": [
    {
      "code": "ERROR_CODE",
      "message": "Human-readable message"
    }
  ]
}

Example 4: 401 Unauthorised

Returned for invalid, expired, or missing API keys.

{
  "errors": [
    {
      "code": "UNAUTHORISED",
      "message": "Unauthorised"
    }
  ]
}

Example 5: 403 Forbidden

Returned when the API key is valid but missing required ability.

{
  "errors": [
    {
      "code": "FORBIDDEN",
      "message": "Forbidden"
    }
  ]
}

Example 6: 404 Not found

Returned when the alert is not found or not accessible.

{
  "errors": [
    {
      "code": "NOT_FOUND",
      "message": "Not found"
    }
  ]
}

Example 7: 422 Unprocessable Entity (invalid date range)

Returned when alert_received_at_gte is greater than alert_received_at_lte.

{
  "errors": [
    {
      "code": "INVALID_DATE_RANGE",
      "message": "alert_received_at_gte cannot be greater than alert_received_at_lte"
    }
  ]
}

Example 8: 422 Unprocessable Entity (invalid enum value)

Returned when action is not one of the supported values.

{
  "errors": [
    {
      "code": "VALIDATION_ENUM",
      "message": "Validation error at ('body', 'update', 'action'). Input should be 'REFUND', 'CANCEL', 'REFUND_AND_CANCEL' or 'ACCEPT_DISPUTE'."
    }
  ]
}

Example 9: 422 Unprocessable Entity (resolved alert cannot be actioned)

{
  "errors": [
    {
      "code": "INVALID_ACTION",
      "message": "Failed to update netalrt_abc123 alert. This alert is in RESOLVED status and cannot be actioned."
    }
  ]
}

Example 10: 422 Unprocessable Entity (no available action)

Returned when the requested action cannot be mapped to any available action for the alert.

{
  "errors": [
    {
      "code": "INVALID_ACTION",
      "message": "Failed to update netalrt_abc123 alert. No available action found."
    }
  ]
}

Example 11: 422 Unprocessable Entity (action execution failed)

Returned when the underlying action execution is rejected.

{
  "errors": [
    {
      "code": "ACTION_FAILED",
      "message": "Failed to update netalrt_abc123 alert. The requested action is not allowed."
    }
  ]
}

Additional reference: 500 Server error

Unexpected server-side failures return:

{
  "errors": [
    {
      "code": "SERVER_ERROR",
      "message": "Server error"
    }
  ]
}