# Scheme notices

List and retrieve scheme notices for accessible organisations.

**Base URL:** `https://api.chargebackstop.com/v1/scheme-notices/`

**Authentication:** Bearer token via API key.

Required abilities:

* `scheme_notices:read` for GET endpoints

**Access scope model:**

* Organisation-level keys can access scheme notices for their own organisation only.
* Admin partner-group keys can access scheme notices across all organisations for their partner.
* Non-admin partner-group keys can access scheme notices only for organisations assigned to their group.

***

## GET /v1/scheme-notices - list scheme notices

Returns a paginated list of scheme notices accessible to the authenticated key.

**API level:** Organisation-level and partner-level\
**Authentication:** `scheme_notices:read`

### Query parameters

| Parameter            | Type     | Description                                                                       |
| -------------------- | -------- | --------------------------------------------------------------------------------- |
| `scheme_notice_type` | string   | Filter by notice type: `TC15`, `TC40`, `SAFE`                                     |
| `organisation_id`    | string   | Filter by organisation ID                                                         |
| `merchant_id`        | string   | Filter by merchant ID                                                             |
| `reported_at_gte`    | datetime | Include scheme notices reported at or after this timestamp (ISO 8601, inclusive)  |
| `reported_at_lte`    | datetime | Include scheme notices reported at or before this timestamp (ISO 8601, inclusive) |
| `sort`               | string   | Sort field: `-reported_at` (default), `reported_at`                               |
| `limit`              | integer  | Number of results per page                                                        |
| `offset`             | integer  | Number of results to skip                                                         |

### Important behaviour

* If both `reported_at_gte` and `reported_at_lte` are sent, `reported_at_gte` must be less than or equal to `reported_at_lte`.
* Default sort order is newest reported notice first (`-reported_at`).

### Example 1 request

```bash
curl -X GET "https://api.chargebackstop.com/v1/scheme-notices/?scheme_notice_type=TC40&sort=-reported_at&limit=20&offset=0" \
  -H "Authorization: Bearer <api_key>"
```

### Example 1 response

```json
{
  "items": [
    {
      "id": "schntc_abc123",
      "organisation_id": "org_xyz456",
      "merchant_id": "mrch_abc123",
      "scheme_notice_type": "TC40",
      "notice_type": "FRAUD_NOTICE",
      "scheme": "VISA",
      "is_revoked": false,
      "notice_revoked_at": null,
      "fraud_reported_at": "2026-02-11T10:30:00Z",
      "transaction_amount_in_cents": 4999,
      "transaction_currency_code": "USD",
      "transaction_card_bin": "424242",
      "transaction_card_last4": "4242",
      "transaction_merchant_name": "EXAMPLE STORE",
      "transaction_merchant_id": "merchant-123",
      "transaction_acquirer_reference_number": "74027012345678901234567",
      "transaction_authorisation_code": "ABC123",
      "transaction_original_date": "2026-02-01T10:30:00Z",
      "transaction_purchase_date": "2026-02-01T10:30:00Z",
      "fraud_type": "CARD_NOT_PRESENT",
      "fraud_dispute_eligible": true,
      "created_at": "2026-02-11T10:31:00Z",
      "updated_at": "2026-02-11T10:31:00Z",
      "links": [
        {
          "rel": "self",
          "uri": "/v1/scheme-notices/schntc_abc123"
        }
      ]
    }
  ],
  "count": 1
}
```

***

## GET /v1/scheme-notices/{scheme\_notice\_id} - get scheme notice by ID

Returns one scheme notice if it is visible to the authenticated key.

**API level:** Organisation-level and partner-level\
**Authentication:** `scheme_notices:read`

### URL parameters

| Parameter          | Type   | Description      |
| ------------------ | ------ | ---------------- |
| `scheme_notice_id` | string | Scheme notice ID |

### Important behaviour

* The same access rules as list scheme notices apply.
* Detail responses include raw/source metadata fields that are not present in the list response.
* Non-existent scheme notices return `404 Not found`.

### Example 2 request

```bash
curl -X GET "https://api.chargebackstop.com/v1/scheme-notices/schntc_abc123" \
  -H "Authorization: Bearer <api_key>"
```

### Example 2 response

```json
{
  "id": "schntc_abc123",
  "organisation_id": "org_xyz456",
  "merchant_id": "mrch_abc123",
  "scheme_notice_type": "TC40",
  "notice_type": "FRAUD_NOTICE",
  "scheme": "VISA",
  "is_revoked": false,
  "notice_revoked_at": null,
  "fraud_reported_at": "2026-02-11T10:30:00Z",
  "transaction_amount_in_cents": 4999,
  "transaction_currency_code": "USD",
  "transaction_card_bin": "424242",
  "transaction_card_last4": "4242",
  "transaction_merchant_name": "EXAMPLE STORE",
  "transaction_merchant_id": "merchant-123",
  "transaction_acquirer_reference_number": "74027012345678901234567",
  "transaction_authorisation_code": "ABC123",
  "transaction_original_date": "2026-02-01T10:30:00Z",
  "transaction_purchase_date": "2026-02-01T10:30:00Z",
  "fraud_type": "CARD_NOT_PRESENT",
  "fraud_dispute_eligible": true,
  "created_at": "2026-02-11T10:31:00Z",
  "updated_at": "2026-02-11T10:31:00Z",
  "source_channel": "VERIFI_INFORM",
  "external_case_id": "case_123",
  "external_notice_key": "inform:123",
  "legacy_fraud_notification_id": null,
  "parent_notice_id": null,
  "enrolment_id": "enrl_abc123",
  "matched_transaction_entity_id": "dpe_abc123",
  "raw_data": {
    "source": "VERIFI"
  },
  "legacy_data_provider_entity_data": null,
  "links": [
    {
      "rel": "self",
      "uri": "/v1/scheme-notices/schntc_abc123"
    }
  ]
}
```

***

## Common error responses

Error responses use this shape:

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

### Example 3 response - 401 unauthorised

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

### Example 4 response - 403 forbidden

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

### Example 5 response - 404 not found

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

### Example 6 response - 422 invalid date range

```json
{
  "errors": [
    {
      "code": "INVALID_DATE_RANGE",
      "message": "reported_at_gte cannot be greater than reported_at_lte"
    }
  ]
}
```