Transaction History

This guide presents some of the options that you have for keeping transaction histories. According to your business use case, you may follow the examples presented here or you can devise other strategies. Along with this guide you might want to read these guides:

• About Transactions — A general explanation of how transactions are handled by the Galileo system.
• About Card Transactions — An explanation of how card transactions work, plus what transaction sequences are produced by different types of card transactions.
• Card Transaction Examples — Different types of card transactions as returned by the Program API.
• Card Transaction Scenarios — Detailed examples of card transactions as they appear in the Auth API, Events API, Program API, and RDFs.

You will need to access your account holders' transaction histories for reasons such as these:

• Present to account holders their transaction histories on your app or website
• Send account holders a monthly statement, summarizing all transactions during that period
• Analyze transaction data for various purposes, such as spending categorization

Which data source to access for transaction histories depends on the use case and the time frame.

• To display a list of transactions on your mobile app or website for the past 30 days or less, Galileo recommends that you use the Program API, as explained in the next section.
• To display a list of transactions that extends past the previous 30 days—or for statements and data analysis—Galileo recommends that you use a transaction history that you create on your own, as described in Building a transaction history.

Obtaining transaction history via API

You can get a comprehensive transaction history for the past 30 days using any of these Program API endpoints. Choose the API depending on your use case.

Get Account Overview

This convenient method retrieves an assortment of account information within a specified date range from multiple other endpoints such as Get Authorization History, Get Transaction History, and Get Balance. It returns a list of authorizations, a list of all other transactions, the account balance, and the account holder profile.

Advantages

• Only includes information that is relevant to account holders. For example, if a transaction has settled, only the settlement is returned, not the authorization.
• Efficient, because authorizations, settlements, other applicable transactions, and the balance are included in a single API request.

Disadvantages

• Lacks some transaction details that are provided in Get All Transaction History and the Event Messages.
• The additional information results in a larger payload, so if you are looking for just authorizations, Get Authorization History is a better option.

Conclusion

Get Account Overview is likely the best option for dashboards that display balance, authorizations, and transactions.

A combination of Get Authorization History and Get Transaction History

Get Authorization History retrieves all unsettled authorizations within a specified date range and Get Transaction History retrieves all settlements and other transactions within a specified date range. Together, they provide the complete set of a cardholder's transactions.

Advantages

• Only includes information that is relevant to cardholders—an authorization is retrieved by Get Authorization History until it has settled, in which case it is retrieved by Get Transaction History.
• Allows authorizations to be retrieved independently of other transactions.
• Because Get Authorization History does not return declined authorizations, combining it with Get Transaction History will provide a complete list of authorizations.

Disadvantages

• Less efficient, because it requires two separate API calls to get all the transactions.
• Lacks some transaction details that are provided in Get All Transaction History and the event messages.

Conclusion

This combination of endpoints may be the right option if your use case requires authorizations to be loaded separately from other transactions and doesn't require granular details.

Get All Transaction History

Get All Transaction History retrieves a comprehensive history of all transactions within a specified date range. Its intended purpose is to provide customer service representatives with abundant context to help them troubleshoot cardholder issues. It offers more detail than most of your customers require.

Advantages

• Provides the most details about each transaction.
• Gets all transaction types in a single API call.

Disadvantages

• Requires you to do additional processing because it includes information that isn't pertinent to your customers. For example, a single card swipe results in multiple transaction records: an authorization, a backout and a settlement. You need to sift through the records to determine which ones are relevant to your customer.
• The additional details result in a large payload.

Conclusion

Get All Transactions History may be the right option if your use case requires granular details and you are willing to filter out extraneous transaction records.

📘

Note

Do not use the calculated_balance value in the Get All Transaction History response for reconciliation or processing. This value is calculated at the time of the API request and so may not accurately portray what the account balance was at the time of the transaction. It is intended only to be a helpful reference and may be shown to customers in your app or used by customer service agents, but it should not be considered authoritative.

Specialized transaction lists

Use these specialized endpoints to get lists of the specific transaction types:

• Get Authorization History
• Get Fee History
• Get Payment History
• Get Deposit History
• Get ACH Transaction History
• Get Hold History
• Get Bill Payment History

These specialized lists can be useful sometimes, but in most cases, your customers will be interested in seeing an aggregated list of transactions.

Building a transaction history

Galileo strongly recommends that its clients maintain their own transaction histories instead of relying exclusively on Galileo data sources. Your data store should be your primary resource for building customer statements and analyzing transaction data, as well as providing your customers with transaction histories that include more than the past 30 days.

When building your own transaction history, you will need to decide among these options:

• Which data sources to use
  • Events API — Live transaction notifications that you can subscribe to, comprising three event message types.
  • Program API — Endpoint calls that can retrieve all transactions or specific types only. (Using this source for time frames larger than 30 days can place significant stress on the Galileo system.)
  • RDF — An authoritative record of all transactions that took place across your programs during a 24-hour period.
• How to uniquely identify a transaction in your database
• Whether to overwrite previous transaction records when an update arrives or maintain the whole list of transactions

Data sources

Galileo offers these data sources for you to build your own transaction history:

Events API

The Events API comprises these transaction-related message types that you can subscribe to:

• Authorization Events — Based on notifications from card networks when a card transaction is authorized
• Settlement Events — Based on notifications from card networks when an authorized transaction is cleared
• Transaction Events — Notifications from the Galileo system about payments, adjustments, fees, and holds

See About the Events API for more information.

Program API

See Obtaining transaction history via API.

RDFs

Every day Galileo sends you RDFs containing an authoritative list of transactions that took place in your program during a 24-hour period. You can use these files to verify that your transaction history is accurate. You can also create new records in your transaction history from these files if your record is missing any transactions.

For more information see the About the RDFs and CDFs guide.

📘

Note

Galileo strongly recommends that you use your RDF datastore when creating customer-facing statements and performing data analysis.

Uniquely identifying transactions

For each authorization, Galileo generates an authorization ID (auth_id) that is unique only within the subnetwork, so an Authorization Event from a Visa card could have the same auth_id as an Authorization Event from Mastercard. Furthermore, Transaction Events are broken down into payments, fees, adjustments, and other types, each of which has an identifier that is unique only within its type. Galileo strongly recommends that you create a unique mapping identifier for each transaction using selected fields from the Events API or Program API messages as well as fields from the RDFs. See Mapping Transactions Within Your System for possible ways to create unique mapping identifiers.

Identifying accounts

Account identifiers within the Galileo system are the PRN, CAD, PAN and balance ID. When creating your own transaction record you may want to include all of these fields for every entry so that you can reconcile your records against different Galileo systems. (If you are not PCI compliant, you will have only a masked PAN.)

This table shows how account identifiers are returned by Galileo systems.

Updating transaction records

Some transactions are completed at the same time they are initiated, such as a fee that is assessed for a transaction. Other transactions are initiated and remain in a pending status until completion, such as a bill payment. Still other transactions begin with an authorization at a point of sale and then pass through a few more steps before settlement. See About Card Transactions for a detailed explanation of card transactions.

In your transaction history, you may use one of these methods to keep track of each transaction's progress:

• Create the initial record, and then when additional information on that transaction arrives, overwrite the data in the initial record with the new information.
• Create a new record for each transaction step as it happens, linking it to the previous step in the sequence.

Transaction sequence initiation

The Events API messages in the lists below can indicate the first step of a transaction sequence.

📘

Note

If the Authorization message contains a non-zero value for original_auth_id, it means that the message does not correspond to the first step of a transaction sequence. The value in original_auth_id contains the auth_id of the previous step of a transaction sequence.

Events marked with an asterisk (*) are both the first and last step of a transaction.

Authorization Events

• AAPM: auth_payment*
• BAUT: auth
• BNSF: denied_auth_nsf*
• BSPM: pmt_split
• CRHD: create_hold
• DAUT: denied_auth*
• IPIN: denied_auth_invalid_pin*
• NACT: denied_auth_inactive_card*
• PUMP: denied_auth_gas*
• STPD: denied_auth_stip*

Transaction Events

• BADJ: adj*
• BPMT: pmt*
• BFEE: fee*
• BPCQ: billpay_request_made

📘

Note

For some of the Transaction Events messages, the initiation and completion steps of the transaction happen at the same time. Others may pend before completion, such as a fee assessed on an account with insufficient funds.

Transaction sequence completion

The Events API messages in the lists below can indicate subsequent steps in a transaction sequence, either intermediary or final.

Authorization Events

• AAAU: auth
• BEXP: auth_exp
• BEXR: auth_exp_reversal
• BSPM: pmt_split

Settlement Events

• SETL: setl

Transaction Events

• ACHC: ach_credit_fail
• ACHR: ach_debit_fail
• ACRT: ach_return
• BDPM: pmt_delayed
• BPAR: billpay_retry
• BPAY: billpay
• BPCC: billpay_check_cleared
• BPCR: billpay_request_returned
• BPEX: billpay_expired
• BSPF: sched_billpay_fail
• BSPM: pmt_split
• EXHD: expire_hold
• FACH: ach_credit_return
• FREV: fee_reversal

How to link a transaction with its previous steps differs depending on the transaction type. See Linking transactions in the About Transactions guide for details.

Transaction sequence examples

These examples describe possible methods to record transaction sequences. In these examples the unique mapping identifier for authorizations is network letter + auth_id, and a latest_version flag tracks which is the latest version of the transaction. For an explanation of the act_type and otype fields see Classifying transactions in the About Transactions guide. For additional examples see Events API Scenarios.

Basic authorization with settlement

For details on how a card transaction (authorization/settlement) works, see About Card Transactions.

This example shows a retail purchase for $50 over Mastercard Banknet rails. First, you receive the Authorization Event message BAUT: auth with these values:

• type: auth
• amount: 50
• act_type: AU
• otype: A
• network: M
• original_auth_id: 0
• auth_id: 33333

The Authorization Event could be recorded in your database like this:

Later, after Mastercard sends the clearing file, you receive the Settlement Event SETL: setl message with these values:

• type: setl
• amount: 50
• act_type: SE
• otype: 5
• network: M
• original_auth_id: 0
• auth_id: 33333

Your database records might look like this:

Because the identifier M33333 has both an authorization (AUA) and a settlement entry (SE5) for the same amount, you know that the transaction is settled.

For more examples of an authorization and settlement transaction, see Three-step sequence in Card Transaction Examples and Scenario 1: Authorization with Settlement.

📘

Note

It is possible for a settlement to contain a partial amount, so a transaction should not be considered complete until settlements equal authorizations. See Incremental clearing in the Settlement guide for more information.

Authorization plus completion

This example shows a $75 preauthorization at a gas pump with a subsequent completion for $25. The network is Visa Interlink. First, you receive the Authorization Event message BAUT: auth with these values:

• type: auth
• amount: 75
• act_type: VI
• otype: L
• network: V
• original_auth_id: 0
• auth_id: 77777

The Authorization Event could be recorded in your database like this:

📘

Note

Authorization event messages for Visa Interlink transactions have network: V, but the settlement event messages have network: I. There are no auth_id collisions among the Visa, Interlink and Plus networks. See Events Network Codes for more information.

Later, you receive the Authorization Event message AAAU: auth with these values:

• type: auth
• amount: 25
• act_type: VI
• otype: C
• network: V
• original_auth_id: 77777
• auth_id: 77788

A completion (C) has the original_auth_id populated with the auth_id of the original preauthorization. When the completion arrives, Galileo backs out the entire $75 preauthorization hold and replaces it with a $25 hold. (To see backouts use the Get All Transaction History endpoint or the CST.) The transaction is not considered settled at this point.

Your database records might look like this:

Later, you receive the Settlement Event SETL: setl message with these values:

• type: setl
• amount: 25
• act_type: IS
• otype: C
• network: I
• original_auth_id: 77777
• auth_id: 77788

This event means that Galileo received a clearing file from Visa and matched the $25 completion. Your database records might look like this:

Because the settlement has the same map_id and amount as the completion, you know that the transaction has settled.

For more examples of a gas pump transaction, see Five-step-sequence in Card Transaction Examples and Scenario 2: Preauthorization with Completion.

Using the RDFs to reconcile

The Authorized Transactions and Posted Transactions files are RDFs that contain a comprehensive list of the previous day's transactions. Use these files to reconcile the transaction records that you gathered from the Events API or the Program API. If there are inconsistencies between the two—for example, if the RDF contains a transaction that your data store does not, or the transaction details don't match—you should consider the information in the RDF to be authoritative.

For more information see the About the RDFs and CDFs guide.

📘

Note

These examples show only some of the RDF fields that are available.

Authorization and settlement example

For example, if your database contains the following entries from the Events API:

The corresponding entries in the Authorized Transactions RDF would look like this:

And the corresponding entries in the Posted Transactions RDF would look like this:

📘

Note

By request, Galileo can include a reversal ID field in the RDFs to track incremental authorizations and other linkage.

Non-network transaction example

One field you can add to the RDFs, SOURCE ID, contains the identifier for the specific transaction: pmt_id, fee_id, adj_id, and so on.

For example, if your database contains the following entries:

In the Posted Transactions RDF, the corresponding entries might look like this: