Alloy's API schemas for transactions are flexible. However, how you map your data to our API fields when designing your integration plays a critical role in which monitoring rules you can build and how those rules perform.

Process Method and Category

The Process Method (process_method) and Category (category) fields are optional, but they often help you build granular, accurate aggregation rules. Both fields are enumerated, so you can use them to group transactions with common characteristics.

Alloy supports the following case-sensitive values for Process Method and Category.

Process Method values

Enum value	Common mapping definition
`Card`	Funds transfer made with a credit, debit, or prepaid card.
`ACH`	Electronic funds transfer that uses the ACH network, including payment, deposit, and withdrawal transfer requests.
`Wire`	Electronic funds transfer managed by the sender's and recipient's banks.
`RTP`	Real-time payments processed through RTP or similar real-time networks, such as FedNow, FPS, or SEPA Instant Credit.
`Cash`	Transactions involving cash, such as ATM or teller withdrawals and deposits.
`Check`	Transactions made by mobile, paper, or cashier's check.
`P2P`	Peer-to-peer transactions made directly between two accounts on the same platform, such as Zelle or Venmo, without an intermediary or third party.
`Internal`	Book transfers, fees, adjustments, and other miscellaneous transactions that occur within your financial institution's ledger.

Category values

Enum value	Common mapping definition
`Deposit`	Inbound bank payments.
`Withdrawal`	Outbound bank payments.
`Return`	Returned or disputed bank payments.
`Purchase`	Card purchases with merchants.
`Purchase Return`	Returned or disputed card transactions.
`Bill Pay`	Automated bank transfers for online bill payment.
`Payment`	Remittance or invoice payments.
`Overdraft Fee`	Account overdraft or nonsufficient funds (NSF) fees.
`Direct Deposit Bonus`	Bonuses awarded for depositing funds.
`Adjustment`	Balance adjustments or other miscellaneous internal transactions.
`Service Charge`	Account maintenance fees, processing fees, and other charges.
`Promo`	Promotional transactions or other rewards.
`Interest`	Accrued interest payments or fees.

Mapping the Process Method field is often straightforward. The Category field is more subjective, and you can adapt it to your business case. In most cases, you'll use Category together with Process Method for two purposes:

Separating transactions within the same Process Method.
Grouping transactions, or strategically separating them, across different Process Methods.

For example, Deposit, Withdrawal, and Return are common Category values for ACH transactions. On card transactions, you can also use Deposit and Withdrawal to show when funds move directly to or from an external card, if your product supports that. However, you'd likely want to separate this activity from other card transactions with merchants, which you can do with other Category values, such as Purchase and Purchase Return.

Status lifecycle and returns

Many payment methods don't move funds immediately, even those that process in seconds. Transactions often move through multiple statuses before they fully post.

When you submit a real-time transaction event to Alloy, you can use the Status (status) field to distinguish each stage of the transaction's lifecycle. For non-return status changes, use the same External Transaction ID (external_transaction_id) on each event to avoid recording duplicate data.

For example, we recommend sending the authorization and settlement of a card transaction as two separate events with different status values, but with the same external_transaction_id on both events. The most common status values for these two stages are Pending and Completed, respectively.

When a transaction is returned or disputed, Alloy recommends using a new External Transaction ID to record the return as its own line item. This ensures Alloy measures historical aggregation rules correctly. You can use your Process Method and Category mappings to specify which transactions are returns and which are part of the typical flow of funds.

Other field recommendations

Is Triggered By User (is_triggered_by_user): A Boolean field that helps you differentiate between two kinds of ACH transactions.
- Your financial institution is the originating depository financial institution (ODFI), and the transaction is a push to or from the monitored account.
- Your financial institution is the receiving depository financial institution (RDFI), and the transaction is a pull to or from the monitored account.
You can also use this field for other payment methods that support both push and pull flows.
Interaction Point (interaction_point): Distinguishes how or where the transaction originated. You can use this field to add a third layer of granularity, although it's often less critical than Process Method and Category.

Unlike Process Method and Category, in some cases it's OK not to specify Interaction Point on every transaction, unless you foresee needing to exclude specific Interaction Point values from rules. This depends on how granular you want your rules in Alloy to be.
Type Code (type_code): Your internal type code or classification for the transaction type. This field is helpful for building rules that capture a very specific subset of transactions, where Alloy's enumerated fields aren't granular enough.
Return Code (return_code): The return code associated with a bank payment return.
Is Approved (is_approved): A generic Boolean field that maps closely to Status. We recommend setting this field to true for whichever Status values you use to indicate that a transaction has posted or settled.