Migration Guide: fraud_notification.created -> scheme_notice.created

This guide explains how to migrate webhook consumers from the deprecated fraud_notification.created event to scheme_notice.created.

What is changing

• fraud_notification.created is deprecated and will be removed on March 31.

• scheme_notice.created is the replacement event for new scheme notice records.

• Event envelope stays the same: id, type, created_at, data.object, api_version.

Compatibility and rollout notes

• Do not listen to fraud_notification.created and scheme_notice.created at the same time in production.

• A dual subscription can create duplicate processing for the same business signal.

• fraud_notification.created events are not remapped onto existing SchemeNotice rows.

• Historical backfill/migration does not emit webhook side effects (no replay).

• Use a strict cutover plan: stop legacy consumption, then start new event consumption.

Payload changes (data.object)

The new event payload is based on SchemeNotice.

Field mapping

Deprecated event (fraud_notification.created)	Replacement (scheme_notice.created)	Notes
id (frdnt_*)	id (schntc_*)	Object id prefix changes
organisation_id	organisation_id	Same
fraud_notification_type	scheme_notice_type	Renamed; allowed values: TC15, TC40, SAFE (fraud_notification.created used TC40/SAFE)
fraud_reported_at	fraud_reported_at	Same semantic meaning
fraud_type	fraud_type	Same
transaction_amount_in_cents	transaction_amount_in_cents	Same
transaction_currency_code	transaction_currency_code	Same
transaction_card_bin	transaction_card_bin	Same
transaction_card_last4	transaction_card_last4	Same
transaction_merchant_name	transaction_merchant_name	Same
transaction_merchant_id	transaction_merchant_id	Same
transaction_acquirer_reference_number	transaction_acquirer_reference_number	Same
transaction_authorisation_code	transaction_authorisation_code	Same
transaction_original_date	transaction_original_date	Same
(not available)	merchant_id	New, nullable
(not available)	notice_type	New (FRAUD_NOTICE or DISPUTE_NOTICE)
(not available)	scheme	New (VISA, MASTERCARD, OTHER)
(not available)	is_revoked	New lifecycle field
(not available)	notice_revoked_at	New lifecycle timestamp
(not available)	fraud_dispute_eligible	New optional boolean
(not available)	transaction_purchase_date	New optional timestamp
(not available)	created_at, updated_at	Object-level timestamps

Example: new event format

Timestamps are RFC 3339 UTC. In production payloads, envelope created_at is emitted as an offset timestamp (for example +00:00), while data.object datetime fields are emitted with a Z suffix. Fractional seconds may appear when present.

{
  "id": "evt_9UYR3Q8xP4aX4Z4uL2YfN",
  "type": "scheme_notice.created",
  "created_at": "2026-02-13T12:17:42+00:00",
  "data": {
    "object": {
      "id": "schntc_8W2tVb13qfHkK3gQ9n7Yp",
      "organisation_id": "org_WVJ7aJzpT32FED9BqKPpM",
      "merchant_id": "mrch_bQXg83B18qgACnp5Y4qU8",
      "scheme_notice_type": "SAFE",
      "notice_type": "FRAUD_NOTICE",
      "scheme": "MASTERCARD",
      "is_revoked": false,
      "notice_revoked_at": null,
      "fraud_reported_at": "2026-02-13T12:15:00Z",
      "transaction_amount_in_cents": 14760,
      "transaction_currency_code": "USD",
      "transaction_card_bin": "411798",
      "transaction_card_last4": "3508",
      "transaction_merchant_name": "ECOM-STUFF OUTLET",
      "transaction_merchant_id": "274953873887879",
      "transaction_acquirer_reference_number": "77198913101798678449413",
      "transaction_authorisation_code": "96JNEP",
      "transaction_original_date": "2026-02-01T08:13:50Z",
      "transaction_purchase_date": null,
      "fraud_type": "CARD_NOT_PRESENT",
      "fraud_dispute_eligible": true,
      "created_at": "2026-02-13T12:16:10Z",
      "updated_at": "2026-02-13T12:16:10Z"
    }
  },
  "api_version": "v1"
}

Consumer migration checklist

1

Prepare your consumer code to support scheme_notice.created

1. Prepare your consumer code to support scheme_notice.created before changing subscriptions.

2

Update parser mappings

• replace fraud_notification_type with scheme_notice_type

• expect object id to use schntc_* prefix

3

Keep existing logic for common fields

Keep existing logic for common fields (fraud_reported_at, transaction_*, fraud_type).

4

Add null-safe handling for new optional fields

Add null-safe handling for new optional fields (merchant_id, transaction_purchase_date, fraud_dispute_eligible, notice_revoked_at).

5

Execute strict cutover in webhook settings

• disable/unsubscribe fraud_notification.created

• enable/subscribe scheme_notice.created

• do not run both subscriptions concurrently in production

6

Keep handler focused on create semantics

Keep your handler focused on create semantics for scheme_notice.created.

Recommended strict cutover strategy

Use a single-event-family cutover to avoid duplicates:

1

Deploy consumer changes that can parse scheme_notice.created

Deploy consumer changes that can parse scheme_notice.created.

2

Switch subscription in one cutover window

In production webhook configuration, switch subscription from fraud_notification.created to scheme_notice.created in one cutover window.

3

Verify delivery and downstream processing

Verify successful delivery and downstream processing.

4

Keep legacy handler for rollback only

Keep legacy handler code temporarily for rollback, but keep legacy subscription disabled unless rolling back.

5

Remove legacy handler after cutover is stable

Remove legacy handler after cutover is stable.