---
updatedAt: 2025-10-02T13:20:55.000Z
agentTools:
  projectIndex: https://developer.alloy.com/public/llms.txt
---

# Transaction

A transaction for a specific Entity and Bank Account has been created or updated.

## Updating an Existing Transaction

If you `POST` to the Events endpoint using the same `external_transaction_id`, Alloy will treat the subsequent `POST`as 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

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th style={{ textAlign: "left" }}>
        Required API Field
      </th>

      <th style={{ textAlign: "left" }}>
        Definition
      </th>

      <th style={{ textAlign: "left" }}>
        Notes
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{ textAlign: "left" }}>
        `timestamp`
      </td>

      <td style={{ textAlign: "left" }}>
        Timestamp of the transaction event.
      </td>

      <td style={{ textAlign: "left" }}>

      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `external_transaction_id`
      </td>

      <td style={{ textAlign: "left" }}>
        Unique identifier for a Transaction.
      </td>

      <td style={{ textAlign: "left" }}>
        Alloy recommends using the same identifier for all status changes of a transaction except for returns and disputes.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        One of:\
        `external_account_id`\
        `bank_account_token`
      </td>

      <td style={{ textAlign: "left" }}>
        Unique identifier for the Bank Account at your financial institution tied to this transaction.
      </td>

      <td style={{ textAlign: "left" }}>
        Immutable field. After transaction is created, Alloy will ignore any updates to this field value.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        One of:\
        `external_entity_id`\
        `entity_token`
      </td>

      <td style={{ textAlign: "left" }}>
        Unique identifier for the Entity (your customer) tied to this transaction.
      </td>

      <td style={{ textAlign: "left" }}>
        The Entity should be attached to the Bank Account record specified the `external_account_id` / `bank_account_token` fields.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `amount`
      </td>

      <td style={{ textAlign: "left" }}>
        Amount in cents. +/- indicate direction of funds.
      </td>

      <td style={{ textAlign: "left" }}>

      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `currency`
      </td>

      <td style={{ textAlign: "left" }}>
        3-character currency code (e.g. "USD").
      </td>

      <td style={{ textAlign: "left" }}>

      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `transaction_created_date`
      </td>

      <td style={{ textAlign: "left" }}>
        ISO 8601 date. Used as the transaction's date or date to look back from when evaluating an account.
      </td>

      <td style={{ textAlign: "left" }}>
        Immutable field. After transaction is created, Alloy will ignore any updates to this field value.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        One of:\
        `counterparty.account_number`,\
        `counterparty.external_counterparty_id`
      </td>

      <td style={{ textAlign: "left" }}>
        Counterparty account that the transaction is with. This is the "other side" of the transaction that is**not** your financial institution's account.
      </td>

      <td style={{ textAlign: "left" }}>

      </td>
    </tr>
  </tbody>
</Table>

### Example Request/Response:

```json Request
{
    "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": {}
    }
}
```
```json Response
{
    "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"
                    }
                }
            }]
    }
}
```