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.account_number`, `counterparty.external_counterparty_id`	Counterparty account that the transaction is with. This is the "other side" of the transaction that isnot your financial institution's account.

Example Request/Response:

{
    "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": {}
    }
}

{
    "status_code": 201,
    "event_request_token": "EV-jalCTa1yXnWqbKYvs05B",
    "_links": {
        "self": {
            "href": "/v1/events/EV-jalCTa1yXnWqbKYvs05B"
        }
    },
    "event": {
        "event_type": "transaction",
        "event_status": "PROCESSED",
        "data": {
            "settled_at": null,
            "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-jalCTa1yXnWqbKYvs05B",
            "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,
            "archived_at": null,
            "counterparty": {
                "account_type": "merchant account",
                "merchant_category_code": null,
                "account_class": null,
                "country_code": "US",
                "entities": [
                    {
                        "entity_token": "B-4x8WzjvGz5Oz8RWA6MvY"
                    }
                ],
                "account_number": "NEW YORK NY #238490",
                "counterparty_token": "A-vjyYKdRm4Zm8NnRqa9FI"
            },
            "external_account_id": "8b75f5e2-b671-450c-9fb2-5aa05c286309",
            "account_token": "A-Rbdws17NItHaEy3HrHkL",
            "transaction_created_date": "2023-12-06T13:57:58.238Z",
            "currency": "USD",
            "external_transaction_id": "087ac67e-17ab-4529-8d1a-a8b2214d305f"
        },
        "evaluations": [
            {
                "error": null,
                "evaluation_token": "L-l09RgNEuI4qkjfAZLfec",
                "workflow_token": "IO33FzOq7zNRl9XXchWnPAZIXgAUiRwx",
                "workflow_version_id": 2,
                "prefiltered": false,
                "summary": {
                    "result": "success",
                    "outcome": "Needs Investigation",
                    "tags": [
                        "Outgoing",
                        "Anomalous Increase in ATM Withdrawals"
                    ]
                },
                "_links": {
                    "self": {
                        "href": "/v1/evaluations/L-l09RgNEuI4qkjfAZLfec"
                    }
                }
            }
        ],
        "journey_applications": [{
                "error": null,
                "journey_application_token": "JA-EiM42mDnJWlGMR1wSBW2",
                "journey_token": "J-FlFujbCsYMUUiXLl5aEX",
                "journey_version_id": 1,
                "source_evaluation_tokens": [
                    "L-l09RgNEuI4qkjfAZLfec"
                ],
                "_links": {
                    "self": {
                        "href": "/v1/journeys/J-FlFujbCsYMUUiXLl5aEX/applications/JA-EiM42mDnJWlGMR1wSBW2"
                    }
                }
            }]
    }
}