Alerts

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

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, 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

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

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

Important behaviour

• 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."
    }
  ]
}

Additional reference: 500 Server error

Unexpected server-side failures return:

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