Transaction

Updating an Existing Transaction

If you POST to the Events endpoint using the same external_transaction_id, Alloy will treat the subsequent POSTas an update to the existing transaction. This mimics the PATCH functionality you may be familiar with in other APIs.

Example Use Case

Real-time fraud monitoring for suspicious transaction patterns, or supplying historical transaction data for a scheduled compliance check.

Request Specifications

Required API Field	Definition	Notes
`timestamp`	Timestamp of the transaction event.
`external_transaction_id`	Unique identifier for a Transaction.	Alloy recommends using the same identifier for all status changes of a transaction except for returns and disputes.
One of: `external_account_id` `bank_account_token`	Unique identifier for the Bank Account at your financial institution tied to this transaction.	Immutable field. After transaction is created, Alloy will ignore any updates to this field value.
One of: `external_entity_id` `entity_token`	Unique identifier for the Entity (your customer) tied to this transaction.	The Entity should be attached to the Bank Account record specified the `external_account_id` / `bank_account_token` fields.
`amount`	Amount in cents. +/- indicate direction of funds.
`currency`	3-character currency code (e.g. "USD").
`transaction_created_date`	ISO 8601 date. Used as the transaction's date or date to look back from when evaluating an account.	Immutable field. After transaction is created, Alloy will ignore any updates to this field value.
One of: `counterparty.identity`, `counterparty.instrument`	The "other side" of the transaction that is not your financial institution's account. You can send an `identity`, an `instrument`, or both.	See Transaction Counterparties for required fields on each object. The legacy `counterparty.account_number` or `counterparty.external_counterparty_id` fields are still supported (see Migrating from Legacy Counterparties).

Example Request/Response:

For more example scenarios, see Transaction Scenarios.

{
    "event_type": "transaction",
    "event_lifecycle_id": "763ca905-6e9c-471d-9f16-d9abc21869f5",
    "event_status": "completed",
    "data": {
        "external_transaction_id": "763ca905-6e9c-471d-9f16-d9abc21869f5",
        "external_account_id": "{{external_account_id}}",
        "external_entity_id": "{{person_external_entity_id}}",
        "timestamp": "2026-11-05T04:27:52.948Z",
        "is_approved": true,
        "transaction_created_date": "2026-11-05T04:27:52.948Z",
        "transaction_settled_date": "2026-11-05T04:27:52.948Z",
        "amount": -2000000,
        "process_method": "Cash",
        "category": "Withdrawal",
        "interaction_point": "ATM",
        "description": "NEW YORK NY #238490 WITHDR 12/6",
        "status": "Completed",
        "status_detail": "Completed - Posted",
        "currency": "USD",
        "is_triggered_by_user": false,
        "type_code": "ATM01",
        "type_description": "ATM Cash Withdrawal",
        "counterparty": {
            "identity": {
                "external_counterparty_identity_id": "BOA NEW YORK NY #238490",
                "type": "merchant",
                "identity_name": "BOA NEW YORK NY #238490 ATM",
                "address_city": "New York",
                "address_state": "NY",
                "address_country_code": "US"
            }
        },
        "supplemental_data": {},
        "meta": {}
    }
}

{
    "status_code": 201,
    "event_request_token": "EV-roNKeD5HZDJD0b3bviJc",
    "_links": {
        "self": {
            "href": "/v1/events/EV-roNKeD5HZDJD0b3bviJc"
        }
    },
    "event": {
        "event_type": "transaction",
        "event_status": "PROCESSED",
        "event_lifecycle_id": "763ca905-6e9c-471d-9f16-d9abc21869f5",
        "data": {
            "transaction_token": "TX-vymkSIN4HnRGJapXs02i",
            "description": "NEW YORK NY #238490 WITHDR 12/6",
            "card_process_mode": null,
            "device_type_code": null,
            "type_code": "ATM01",
            "type_description": "ATM Cash Withdrawal",
            "is_approved": true,
            "approval_code": null,
            "is_reversal": null,
            "batch_identifier": "EV-roNKeD5HZDJD0b3bviJc",
            "meta": null,
            "category": "Withdrawal",
            "is_triggered_by_user": false,
            "is_international_override": null,
            "amount": "-2000000",
            "interaction_point": "ATM",
            "status": "Completed",
            "status_detail": "Completed - Posted",
            "process_method": "Cash",
            "return_code": null,
            "return_code_reason": null,
            "entry_mode": null,
            "iso_message": null,
            "response_code": null,
            "sec_code": null,
            "archived_at": null,
            "db_created_at": "2026-11-05T04:27:52.948Z",
            "external_account_id": "6a44c725-86f0-4f86-8aec-fa9d0868ff0e",
            "account_token": "A-28hgLcsw5kUcIYDXRmNB",
            "transaction_created_date": "2026-11-05T04:27:52.601Z",
            "transaction_latest_date": "2026-11-05T04:27:52.601Z",
            "currency": "USD",
            "counterparty": {
                "identity": {
                    "counterparty_identity_token": "CID-X27ts4g8ZeOnmNAmTQfE"
                }
            },
            "entity_token": "P-r392y6q4z4GS2hf0jeI7",
            "transaction_settled_date": null,
            "external_entity_id": "babe5309-59e2-4211-9c0a-5eaa6e5ae0b0",
            "external_transaction_id": "763ca905-6e9c-471d-9f16-d9abc21869f5"
        },
        "evaluations": [],
        "journey_applications": []
    }
}

{
    "event_type": "transaction",
    "event_lifecycle_id": "e3065d04-95aa-47a1-915c-84b575ff3855",
    "event_status": "completed",
    "data": {
        "external_transaction_id": "e3065d04-95aa-47a1-915c-84b575ff3855",
        "external_account_id": "8b75f5e2-b671-450c-9fb2-5aa05c286309",
        "external_entity_id": "cf88a0a1-34d6-492d-b617-c8b43785e7b7",
        "timestamp": "2023-12-06T13:54:39.735Z",
        "is_approved": true,
        "transaction_created_date": "2023-12-06T13:54:39.735Z",
        "transaction_settled_date": "2023-12-06T13:54:39.735Z",
        "amount": -2000000,
        "process_method": "Cash",
        "category": "Withdrawal",
        "interaction_point": "ATM",
        "description": "NEW YORK NY #238490 WITHDR 12/6",
        "status": "Completed",
        "status_detail": "Completed - Posted",
        "currency": "USD",
        "is_triggered_by_user": false,
        "type_code": "ATM01",
        "type_description": "ATM Cash Withdrawal",
        "counterparty": {
            "external_counterparty_id": "BOA NEW YORK NY #238490",
            "account_type": "merchant account",
            "account_name": "BOA NEW YORK NY #238490 ATM",
            "account_number": "BOA NEW YORK NY #238490",
            "country_code": "US"
        },
        "supplemental_data": {},
        "meta": {}
    }
}