Counterparties

A counterparty is the other side of a transaction: the party that isn't your institution's account. In the typed counterparty schema, the counterparty on a transaction event has two parts, and each part has its own external ID:

identity: who the counterparty is, such as a person, business, or merchant.
instrument: how the counterparty paid or was paid, such as with a bank account, card, digital wallet, or another payment method.

You can send an identity, an instrument, or both on a single transaction, depending on what you know about the counterparty. Alloy matches each object only by its external ID and doesn't fall back to other attributes like name or account number. If an identity or instrument doesn't include its external ID, Alloy rejects it.

One identity can be associated with many instruments over time. For instance, Example Smoothie Shop is one identity whether it sends payroll from one bank account or five. Similarly, a cardholder with two cards is one identity with two instruments. When you send both IDs, your rules can track a counterparty across all the accounts and cards that it uses, and track every counterparty that uses the same instrument.

If you send the legacy counterparty schema today, see Migrate from legacy counterparties.

🚧
Caution
Don't use a full card number or raw bank account number as an external ID. Instead, use a card token or fingerprint from your processor, or your own surrogate key. Choose IDs that stay the same for the life of the counterparty and that don't contain sensitive data.

Example

The following counterparty object is from an online card payment. The identity is the shopper, and the instrument is the card that the shopper used. Transaction fields outside of counterparty don't change.

"counterparty": {
    "identity": {
        "external_counterparty_identity_id": "e4163207-d094-4996-82f0-ee99731c9452",
        "type": "person",
        "name_first": "Johnny",
        "name_last": "Appleseed",
        "email_address": "[email protected]",
        "address_postal_code": "94045",
        "address_country_code": "US"
    },
    "instrument": {
        "external_instrument_id": "6bad6be2-8e7a-46e9-9f19-950499dd251d",
        "instrument_type": "card",
        "card_last4": "1111",
        "card_network": "Visa",
        "name_on_card": "Johnny Appleseed"
    }
}

For complete payloads across different payment rails, see Counterparty scenarios.

Identity and instrument fields

Each object requires an external ID, and every other field is optional. The following sections summarize the available fields. For the full list of allowed values and validation rules, see the Create an event API reference.

Identity object

The following table summarizes the fields in the identity object:

Field	Description
`external_counterparty_identity_id`	Required. Your stable ID for this person, business, or merchant.
`type`	One of the following values: `person`, `business`, `merchant`, or `customer`.
`identity_name`, `name_first`, `name_last`, `dba_name`	Names for a business, merchant, or person.
`birth_date`, `email_address`, `phone_number`	Contact and identification details.
`address_line_1`, `address_line_2`, `address_city`, `address_state`, `address_postal_code`, `address_country_code`	Address details.
`merchant_identifier`, `merchant_category_code`, `mcc_description`	Merchant details.
`external_entity_id`	Links the identity to an existing Entity. Alloy doesn't create a new Entity from this field.
`device`	The device that the counterparty used. Requires `external_device_id`. Accepts either `ip_address_v4` or `ip_address_v6`, but not both.

Instrument object

Not every field applies to every instrument_type, so you can omit fields that don't apply, such as card fields on a bank account. The following table summarizes the fields in the instrument object:

Field	Applies to	Description
`external_instrument_id`	All	Required. Your stable ID for this account, card, or wallet. Must be 1 to 256 characters.
`instrument_type`	All	Required. One of the following values: `bank_account`, `card`, `digital_wallet`, or `other`.
`routing_number`, `routing_number_type`, `account_number`, `account_number_last4`, `account_holder_name`, `account_type`	Bank account	`account_number_last4` must be four digits. `account_type` is one of `checking`, `savings`, `deposit`, `credit`, or `other`.
`card_bin`, `card_last4`, `card_network`, `name_on_card`, `avs`, `form_factor`, `expiration_month`, `expiration_year`	Card	`card_bin` must be six digits. `card_last4` and `expiration_year` must be four digits. `form_factor` is `physical` or `virtual`.
`wallet_provider`, `wallet_identifier`	Digital wallet
`check_number`, `payee_name_raw`	Other, such as checks
`country_code`, `currency`	All	`currency` can be up to three characters.