Guides
  1. Ongoing Monitoring
  2. Integrating with Events
  3. Creating Entities and Accounts

Card Accounts

If your institution issues payment cards, you can create Card objects in Alloy to represent the cards that are issued for a particular Bank Account. Card records allow Alloy to associate card-level activity with the correct Entity and Account for monitoring purposes.

Cards must be created after both the Entity and Bank Account records they belong to. You can create Cards using the card_created event type.

Similar to how Accounts use external_account_id as a unique identifier, you'll need to supply an external_card_id when creating a Card record. This should map to however you uniquely identify a card in your system of record.

The entities[] and accounts[] arrays are required fields when creating new Card records. The accounts[] array should reference the Bank Account the Card is issued for, using the same external_account_id you assigned when creating that Account.

For real-time integrations, Alloy recommends submitting a card_created event as soon as a card is issued and its identifier is known. If the new Card is being issued as a replacement or re-issuance of a previous Card — for example, due to a lost, stolen, or damaged card — you can indicate this by including the replaces_external_card_id field with the external_card_id of the prior Card, and a replacement_reason to describe why the new Card was issued.

{
    "event_type": "card_created",
    "event_status": "successful",
    "event_lifecycle_id": "312814e7-e038-4375-b10e-6e6e6235734b",
    "data": {
        "external_card_id": "312814e7-e038-4375-b10e-6e6e6235734b",
        "external_entity_id": "e96dbfa4-7cf4-4881-b8a0-3720ea72913f",
        "timestamp": "2026-06-12T17:56:22.217Z",
        "card_name": "Platinum Debit",
        "product_name": "Checking Debit",
        "product_code": "CHK-001",
        "card_type": "debit",
        "form_factor": "physical",
        "issued_at": "2026-06-01T17:56:22.217Z",
        "expiry_month": "06",
        "expiry_year": "2029",
        "status": "pending_activation",
        "status_detail": "Card has been sent for activation",
        "is_locked": false,
        "entities": [
            {
                "card_holder_type": "primary",
                "external_entity_id": "e96dbfa4-7cf4-4881-b8a0-3720ea72913f"
            }
        ],
        "accounts": [
            {
                "external_account_id": "8b75f5e2-b671-450c-9fb2-5aa05c286309",
                "account_type": "primary"
            }
        ],
        "replaces_external_card_id": "07e81a74-3fa9-4034-92d4-d59a0e92fdd2",
        "replacement_reason": "lost"
    }
}
{
    "status_code": 201,
    "event_request_token": "EV-6duCPBpd1S4ho2J8HKse",
    "_links": {
        "self": {
            "href": "/v1/events/EV-6duCPBpd1S4ho2J8HKse"
        }
    },
    "event": {
        "event_type": "card_created",
        "event_status": "PROCESSED",
        "event_lifecycle_id": "312814e7-e038-4375-b10e-6e6e6235734b",
        "data": {
          "external_card_id": "312814e7-e038-4375-b10e-6e6e6235734b",
          "external_entity_id": "e96dbfa4-7cf4-4881-b8a0-3720ea72913f",
          "timestamp": "2026-06-12T17:56:22.217Z",
          "card_name": "Platinum Debit",
          "product_name": "Checking Debit",
          "product_code": "CHK-001",
          "card_type": "debit",
          "form_factor": "physical",
          "issued_at": "2026-06-01T17:56:22.217Z",
          "expiry_month": "06",
          "expiry_year": "2029",
          "status": "pending_activation",
          "status_detail": "Card has been sent for activation",
          "is_locked": false,
          "entities": [
              {
                  "card_holder_type": "primary",
                  "external_entity_id": "e96dbfa4-7cf4-4881-b8a0-3720ea72913f"
              }
          ],
          "accounts": [
              {
                  "external_account_id": "8b75f5e2-b671-450c-9fb2-5aa05c286309",
                  "account_type": "primary"
              }
          ],
          "replaces_external_card_id": "07e81a74-3fa9-4034-92d4-d59a0e92fdd2",
          "replacement_reason": "lost"
        },
        "evaluations": [],
        "journey_applications": []
    }
}

If you need to update a Card record after it's been created — for example, when a card is locked, replaced, or its status changes — you can do so using the card_updatedevent type.

{
    "event_type": "card_updated",
    "event_status": "successful",
    "event_lifecycle_id": "d1c63d84-c7b6-4ee6-a841-641b23c83aef",
    "data": {
        "external_card_id": "07e81a74-3fa9-4034-92d4-d59a0e92fdd2",
        "external_entity_id": "e96dbfa4-7cf4-4881-b8a0-3720ea72913f",
        "timestamp": "2026-06-01T17:56:22.217Z",
        "status": "deactivated",
        "status_detail": "Card is locked & deactivated",
        "is_locked": true,
        "lock_expires_at": null
    }
}
{
    "status_code": 201,
    "event_request_token": "EV-tHc3r3odrpkdtb1ViNHD",
    "_links": {
        "self": {
            "href": "/v1/events/EV-tHc3r3odrpkdtb1ViNHD"
        }
    },
    "event": {
        "event_type": "card_updated",
        "event_status": "PROCESSED",
        "event_lifecycle_id": "d1c63d84-c7b6-4ee6-a841-641b23c83aef",
        "data": {
            "external_card_id": "07e81a74-3fa9-4034-92d4-d59a0e92fdd2",
            "card_token": "CARD-wdshFFRC93rw6DeYjRVL",
            "timestamp": "2026-06-01T23:15:00.000Z",
            "external_entity_id": "e96dbfa4-7cf4-4881-b8a0-3720ea72913f",
            "is_locked": true,
            "lock_expires_at": null,
            "status": "deactivated",
            "status_detail": "Card is locked & deactivated"
        },
        "evaluations": [],
        "journey_applications": []
    }
}