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` (Ethoca only), `RESOLVED`, `INVALID`
`organisation_id`	string	Filter by organisation ID
`merchant_id`	string	Filter by merchant ID. Matches alerts whose enrolment includes this merchant, in any position of `merchant_ids`
`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",
      "merchant_ids": ["mrch_abc123", "mrch_def789"],
      "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",
  "merchant_ids": ["mrch_abc123", "mrch_def789"],
  "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",
  "merchant_ids": ["mrch_abc123", "mrch_def789"],
  "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": "action: Input should be 'REFUND', 'CANCEL', 'REFUND_AND_CANCEL' or 'ACCEPT_DISPUTE'.",
      "path": "action"
    }
  ]
}

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