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.
Identifier | RDFs | Program API | Events API | Auth API |
---|---|---|---|---|
PRN | PRN | pmt_ref_no | pmt_ref_no | prn |
CAD | CARD ID | card_id | cad | cad |
PAN | CARD NUMBER | card_number | protected_pan_four | pan |
Balance ID | GALILEO ACCOUNT ID | bal_id galileo_account_number | balance_id | โ |
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 inoriginal_auth_id
contains theauth_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:
map_id | amount | trans_code | original_auth_id | latest_version |
---|---|---|---|---|
M33333 | -50.00 | AUA | 0 | True |
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:
map_id | amount | trans_code | original_auth_id | latest_version |
---|---|---|---|---|
M33333 | -50.00 | AUA | 0 | False |
M33333 | -50.00 | SE5 | 0 | True |
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:
map_id | amount | trans_code | original_auth_id | latest_version |
---|---|---|---|---|
V77777 | -75.00 | VIL | 0 | True |
Note
Authorization event messages for Visa Interlink transactions have
network: V
, but the settlement event messages havenetwork: I
. There are noauth_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:
map_id | amount | trans_code | original_auth_id | latest_version |
---|---|---|---|---|
V77777 | -75.00 | VIL | 0 | False |
V77788 | -25.00 | VIC | V77777 | True |
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:
map_id | amount | trans_code | original_auth_id | latest_version |
---|---|---|---|---|
V77777 | -75.00 | VIL | 0 | False |
V77788 | -25.00 | VIC | V77777 | False |
V77788 | -25.00 | ISC | V77777 | True |
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:
balance_id | trans_code | auth_id | amount | original_auth_id | network | map_id |
---|---|---|---|---|---|---|
33333 | AUA | 717 | -25.00 | 0 | M | M717 |
55555 | ISA | 414 | -30.00 | 0 | V | V414 |
33333 | SE5 | 717 | -40.00 | 0 | M | M717 |
The corresponding entries in the Authorized Transactions RDF would look like this:
GALILEO ACCOUNT ID | TRANSACTION AMOUNT | AUTHORIZATION CODE | NETWORK CODE |
---|---|---|---|
33333 | 25.00- | 717 | M |
And the corresponding entries in the Posted Transactions RDF would look like this:
GALILEO ACCOUNT ID | TRANSACTION CODE/TYPE | TRANSACTION AMOUNT | AUTHORIZATION CODE | NETWORK CODE |
---|---|---|---|---|
55555 | ISA | 30.00- | 414 | V |
33333 | SE5 | 40.00- | 717 | M |
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:
balance_id | payment_id | fee_id | adj_id | amount | trans_code | map_id |
---|---|---|---|---|---|---|
22222 | 202 | +50.00 | PMRC | PM-202 | ||
66666 | 505 | -3.00 | FE01 | FE-505 | ||
44444 | 303 | +40.00 | PMDD | PM-303 | ||
44444 | 707 | -20.00 | ADA | AD-707 |
In the Posted Transactions RDF, the corresponding entries might look like this:
GALILEO ACCOUNT ID | TRANSACTION CODE/TYPE | TRANSACTION AMOUNT | SOURCE ID |
---|---|---|---|
22222 | PMRC | 50.00+ | 202 |
66666 | FE01 | 3.00- | 505 |
44444 | PMDD | 40.00+ | 303 |
44444 | ADA | 20.00- | 707 |
Updated 6 days ago