Transaction Reporting – Transaction Families

A transaction family includes all transactionId’s that comprise the complete transaction hierarchy. This allows merchants to query against an entire transaction family and view each transaction in its processing sequence within the hierarchy.

Understanding Transaction Families

All transactions—regardless of whether it’s an authorization or a subsequent transaction such as an incremental authorization, return, or void—are assigned a unique transactionId in the transaction database. As a result, any transaction can be easily queried by this unique transactionId.

However, there are instances when a merchant may want to view a specific transaction within the context of the entire transaction hierarchy. This hierarchical relationship is managed by a family identifier (FamilyId) that links all related transaction data returned during transaction family query requests. A transaction family includes all transactionId’s that comprise the complete transaction hierarchy. This allows merchants to query against an entire transaction family and view each transaction in its processing sequence within the hierarchy.

To better understand the concept of a transaction family, consider the typical Retail/Restaurant, Terminal Capture, Credit transaction workflow below:

Authorize –> Adjust –> Capture –> ReturnById

1. Merchant submits an authorization for $25.00 (transactionId = 11111).
2. Merchant performs an incremental authorization for $5.00 (transactionId = 22222).
3. Merchant captures and settles the transaction for $30.00 (transactionId = 33333).
4. Customer returns the item to the merchant. The merchant initiates a return transaction for the total authorized amount of $30.00 (transactionId = 44444).

Performing a query on a single transactionId only returns the transaction data associated with that transaction. For example, querying the transaction database where transactionId = ‘11111’ will return the details of the initial authorization only.

However, querying the transaction database using the QueryTransactionFamilies operation (where transactionId = ‘11111’) returns the requested transaction in addition to all transactionId’s related to the entire transaction hierarchy. This allows merchants to have a much better view into the current status of a particular transaction in the context of the overall transaction history.

Understanding Family States

Regardless of the state of individual transactions within a transaction family, you can also query the overall transaction family state (FamilyState) which takes into consideration all transactions in the transaction sequence.

Workflow Examples

Let’s revisit our previous transaction sequence example which represents a typical Retail/Restaurant, Terminal Capture, Credit transaction:

Authorize –> Adjust –> Capture –> ReturnById

1. Merchant submits an authorization for $25.00 (transactionId = 11111).
2. Merchant performs an incremental authorization for $5.00 (transactionId = 22222).
3. Merchant captures and settles the transaction for $30.00 (transactionId = 33333).
4. Customer returns the item to the merchant. The merchant initiates a return transaction for the total authorized amount of $30.00 (transactionId = 44444).

Based on this workflow, the following states are recorded in the transaction database:

Based on the transaction sequence above, the final FamilyState would be “Returned” and the net amount (inclusive of all transactions in the family) would be “0.00”.

For more information about the relationship between TransactionState, CaptureState, and FamilyState, refer to Expected Transaction and Capture States.