Transaction Creation vs. Update

Unlike other event types, Alloy's transaction event type is flexible and can be used for creating new Transaction records in Alloy's system or for updating a Transaction that we've already received. This means that you can safely submit multiple events for the same external_transaction_id. The timestamp field can be used to help protect against Alloy updating transaction data in the wrong order. For example, if you submit:

• Event Request #1:

{
  "event_type": "transaction",
  "data": {
    "timestamp": "2024-03-22T00:00:00Z",
    "external_transaction_id": "123",
    "status": "Completed"
  }
}

• Event Request #2

{
  "event_type": "transaction",
  "data": {
    "timestamp": "2024-03-21T23:59:30Z",
    "external_transaction_id": "123",
    "status": "Pending"
  }
}

Even if Request #2 is received by Alloy after Request #1, Alloy will still retain a transaction status of Completed since the timestamp of Request #2 is before the timestamp submitted on Request #1.

Please note that certain fields, including transaction_created_dateandexternal_account_id are immutable and any updated information will be ignored.

Field Mapping

Although Alloy’s API schemas for transactions are extremely flexible, how you map to our API fields when designing your integration will play a critical role in what monitoring rules you can build and how those rules will perform.

Using Process Method and Category

The Process Method (process_method) and Category (category) fields are optional fields that are often extremely helpful for building granular, accurate aggregation rules. Both fields are enumerated and can be used to bucket transactions with common characteristics.

Alloy currently supports the following values (case sensitive) for Process Method and Category:

Process Method

Category

While mapping the Process Method field is often straightforward, the Category field is more subjective and can be adapted more depending on your business case. However, it's typically used in combination 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 commonly used values for Category on ACH transactions. On Card transactions, you may also use ‘Deposit’ and ‘Withdrawal’ to indicate when funds are moved directly to or from an external card, if that’s something your product supports. However, you’d likely want to separate this activity from other Card transactions with merchants, which you can do using other Category values (like ‘Purchase’ and ‘Purchase Return’).

Status Lifecycle and How to Handle Returns

Most transaction payment methods - even those that process in a matter of seconds - don’t move funds immediately and often move through multiple statuses before the transaction is fully posted. When you submit a real-time transaction event to Alloy, you can use the Status (status) field to differentiate each stage of the transaction as it moves through its lifecycle. For non-return status changes, you should use the same External Transaction ID (external_transaction_id) on each event to avoid recording duplicated data.

• For example, we recommend sending authorization and settlement of a Card transaction as two different events with different Status values (Pending and Completed are the enum values most commonly used for these two Card stages respectively), but use the same External Transaction ID on both events.

When a transaction is returned (or disputed), Alloy recommends using a new External Transaction ID to record the return as its own line item to ensure that historical aggregation rules are measured correctly. You can use the Process Method and Category field mappings to specify which transactions are returns vs. typical flow of funds.

Other Field Recommendations

• Is Triggered By User (is_triggered_by_user): boolean field is valuable to differentiate ACH transactions where your financial institution is the ODFI (the transaction is a push to/from the monitored account) vs. the RDFI (where the transaction is a pull to/from the monitored account). You can also use it for other payment methods which support both push and pull flows.
• Interaction Point (interaction_point): field can also be used to add a third layer of granularity, although it is often less critical than Process Method and Category. This field is used to distinguish how or where the transaction originated.
  As opposed to Process Method and Category, in some cases it’s okay not to specify Interaction Point on all transactions, unless you foresee the need to exclude specific Interaction Point enums from rules. This depends on the granularity of the rules you want to build in Alloy.
• Type Code (type_code): your internal type code or classification for the transaction type. Helpful for building rules that are designed to capture a very specific subset of transactions where Alloy’s enumerated fields aren’t granular enough.
• Return Code (return_code): Return code associated with bank payment returns.
• Is Approved (is_approved): generic, boolean field which maps closely to Status. We recommend mapping this field to true for whichever transaction Status enums you use to indicate when a transaction has been posted or settled.