Log into Sandbox

This guide contains instructions for presenting your account holders' transaction histories. Along with this guide you might want to read these other guides:

  • <a href="doc:about-transactions" target="_blank">**About Transactions**</a> — How transactions are handled by the Galileo system.

  • <a href="page:finding-transaction-data" target="_blank">**Finding Transaction Data**</a> — Quick reference to see where to find different types of transactions.

  • <a href="doc:about-the-rdfs-and-cdfs" target="_blank">**About the RDFs and CDFs**</a> — An explanation of the RDFs and CDFs that you can use to build a datastore.

  • <a href="doc:about-the-events-api" target="_blank">**About the Events API**</a> — An explanation of the Events APIs and their implementation.

You 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

## API-first strategy

Galileo recommends the API-first strategy to all new clients. Legacy clients might also find that API-first is a better solution for them, because it doesn't include building a datastore that attempts to parallel the Galileo ledger in real time.

Note

The legacy method, which may be better for programs that maintain their own account balances, has been moved to <a href="page:building-a-transaction-datastore" target="_blank">Building a Transaction Datastore</a>.

### Presenting recent transaction history

Transactions younger than 30 days are often in a state of flux: a pending authorization can be reversed, it can settle for a different amount, or it could expire. ACH and billpay transactions are sometimes returned and reversed. This variability presents a challenge when trying to display the latest information to your customers. The most reliable way to present current data is to call the Program API every time a customer accesses a page in your app or website; however, that can result in an undesirably high number of API calls, and if the transactions are older than 30 days, the response from the Program API can be unacceptably delayed.

To ensure that you always present the latest version of the data, while minimizing the number of API calls, Galileo recommends an "API-first" strategy for transactions that are younger than 30 days old. (For transactions older than 30 days, go to [Presenting older transaction history](🔗)). The API-first strategy combines the Program API with the Events API to maintain a cache that always contains the latest data.

The API-first strategy follows this process:

  1. A customer accesses your web site or mobile app for the first time.

  2. You call the Program API and cache the response.

  3. The interface retrieves the data from the cache and presents it.

  4. The next time the customer accesses the interface, you do one of the following, depending on whether you have received an Events API message for the account:

    • **No message received** — Present the cached data.

    • **Message received** — Call the Program API again, overwrite the data in the cache, and present the new data.

#### API-first setup

To follow the API-first strategy, you will need to set up the following:

  • Decide which [Program API endpoints](🔗) you want to call to present data in your interface.

  • Create a datastore to hold the responses from the Program API. This datastore will act as a cache that your interface always draws on when presenting data.

  • Subscribe to Events API messages <a href="page:events-that-affect-the-balance" target="_blank">that affect the available balance</a>, according to your use case.

    • If you will also present customer profile information (using <a href="ref:post_getaccountoverview" target="_blank">Get Account Overview</a>), you should also subscribe to the <a href="ref:webhook_account_event_post" target="_blank">Account Events</a> webhooks that indicate a change to the customer profile.

  • Decide on a "staleness" interval, which determines how old a cached response can be before it is considered expired.

  • Consume the daily <a href="doc:secondary-rdf-reference#posted-transactions-rdf" target="_blank">Posted Transactions RDF</a> as well as any <a href="doc:cdf-reference" target="_blank">CDFs</a> you might want.

  • Create another datastore to hold the transactions from the RDFs and CDFs.

##### Conventions

  • The interface must always draw from a "clean" cache. A clean cache has the latest account data.

  • When the cache is not clean, it must be refreshed by calling the Program API.

  • Two conditions affect whether the cache is clean:

    • **Staleness interval** — After this interval, the data is considered to be "stale."

    • **Events API messages** — The arrival of an event automatically invalidates the cached data, rendering it "dirty."

  • As desired, you can add your own enriched data to the cache before presenting the data to the customer.

#### API-first workflow



<!--api-first-flowchart.png..-->

  1. When the customer logs in to the interface for the first time, the interface calls the Program API to populate the cache.

  2. The interface pulls data from the cache to present to the customer.

  3. The cache is considered clean until one of these things happens:

    • An Events API message arrives.

    • The staleness interval elapses.

  4. The next time the customer accesses the interface, application logic determines whether the cache is clean.

    • **Not clean** — The interface calls the Program API to refresh the cache.

    • **Clean** — The interface does not call the Program API.

  5. The interface pulls data from the cache to present to the customer.

### Presenting older transaction history

Transactions older than 30 days are almost always stable. Pending authorizations have usually expired, and ACH and billpay returns don't usually take a month. To retrieve these transactions, you can use a datastore that you have created from the daily RDF and CDF files that Galileo sends.

This is the process:

  1. Read the daily Posted Transactions RDF and any CDFs into a separate datastore. See <a href="doc:about-rdfs-and-cdfs#building-a-datastore" target="_blank">Building a datastore</a> in the _About RDFs and CDFs_ guide for more information.

  2. A customer accesses your interface to see a list of transactions that are older than 30 days.

  3. You retrieve the transactions from your RDF datastore to present to the customer.

## Data sources

Galileo offers these data sources for you to present a transaction history:

### Events API

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

  • <a href="ref:webhook_authorization_event_post" target="_blank">Authorization Events</a> — Based on notifications from <<glossary:card network>>s when a card transaction is authorized

  • <a href="ref:settlement-events-webhook" target="_blank">Settlement Events</a> — Based on notifications from card networks when an authorized transaction is cleared

  • <a href="ref:transaction-events-webhook" target="_blank">Transaction Events</a> — Notifications from the Galileo system about payments, adjustments, fees, and holds

See <a href="doc:about-the-events-api" target="_blank">About the Events API</a> for more information.

### RDFs

Every day Galileo sends you <<glossary:RDF>>s 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 <a href="doc:about-rdfs-and-cdfs" target="_blank">About the RDFs and CDFs</a> guide. Also see <a href="doc:transaction-ids" target="_blank">Transaction IDs</a> for information on constructing unique IDs for each transaction.

Note

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

### Program API

When calling the Program API to present data to the customer, choose the endpoint according to your use case:

  • [Account landing page](🔗)

  • [Balance only](🔗)

  • [Completed transactions](🔗)

  • [Pending transactions](🔗)

  • [Declined transactions](🔗)

  • [Billpay transactions](🔗)

  • [Deposits](🔗)

  • [Transfers](🔗)

  • [Fees](🔗)

  • [Holds](🔗)

#### Account landing page

When your customers open your app or go to your website, they expect to see a snapshot of relevant information: balance and recent transactions are common items to display. For this use case, Galileo recommends the <a href="ref:post_getaccountoverview" target="_blank">Get Account Overview</a> endpoint. It returns:

  • Customer profile information

  • Account balance (available funds for debit or unpaid balance for credit)

  • Pending card purchases

  • Posted transactions, including settled authorizations, deposits, withdrawals, and fees

You can specify a date range for the transactions to display. Also included are:

  • PRN (account number)

  • Card shipping address

  • Pending fees

  • Holds

  • Savings / non-Savings interest

#### Balance only

If you want to show only the available balance on your interface, use the <a href="ref:post_getbalance" target="_blank">Get Balance</a> endpoint. It returns:

  • Available balance

  • Pending billpay transactions

  • Balance without including card transactions

You can also get the balance from the Get Account Overview endpoint response, but that endpoint returns a large amount of data, which might increase latency.

#### Completed transactions

To show only the transactions that have been posted to the account (not including pending transactions), call the <a href="ref:post_gettranshistory" target="_blank">Get Transaction History</a> endpoint. For the specified timespan, it returns:

  • Settled card transactions

  • Deposits

  • Withdrawals

  • Transfers

  • Fees

#### Pending transactions

Pending card transactions—authorizations that have not settled, expired, or been reversed—are returned by the <a href="ref:post_getauthhistory" target="_blank">Get Authorization History</a> endpoint.

#### Declined transactions

To show all declined or rejected transaction types, you have to combine the results of a few endpoints:

  • <a href="ref:post_getalltranshistory" target="_blank">Get All Transaction History</a> — Transactions that have a deny code.

  • <a href="ref:post_getachtranshistory" target="_blank">Get ACH Transaction History</a> — Transactions that have a reject code.

  • <a href="ref:post_getbillpayhistory" target="_blank">Get Bill Payment History</a> — Transactions in a <a href="ref:api-reference-bill-payment-statuses" target="_blank">canceled or return status</a>.

#### Billpay transactions

With billpay transactions you can display a list of all payments for all billers, or you can list the transactions per biller. Call <a href="ref:post_getbillpayhistory" target="_blank">Get Bill Payment History</a> for a specified timespan or call <a href="ref:post_getscheduledbillpayments" target="_blank">Get Scheduled Bill Payments</a> for payments that are scheduled for future dates.

#### Deposits

You can display funds that are deposited into a customer account by calling one of several endpoints:

  • <a href="ref:post_getdeposithistory" target="_blank">Get Deposit History</a> — During program setup, you can specify which kinds of ACH deposits are returned by this endpoint.

  • <a href="ref:post_getachtranshistory" target="_blank">Get ACH Transaction History</a> — This endpoint returns all ACH transactions. You can filter out the debits to display only the credits.

  • <a href="ref:post_getpaymenthistory" target="_blank">Get Payment History</a> — This endpoint returns all funds that credit the account, regardless of source.

#### Transfers

You can define transfers as bank-to-bank transfers (ACH transactions) or you can include peer-to-peer funds movement.

  • <a href="ref:post_getachtranshistory" target="_blank">Get ACH Transaction History</a> — Returns all bank-to-bank transfers, both incoming and outgoing.

  • <a href="ref:post_gettranshistory" target="_blank">Get Transaction History</a> — Select transactions that have MCCs for peer-to-peer funds movement. You might need to do a bit of research to find which MCCs apply to your use case.

#### Fees

To display fees by themselves, call one of these endpoints:

  • **Total**

    • <a href="ref:post_getfeesummary" target="_blank">Get Fee Summary</a> — Returns year-to-date and month-to-date totals for the specified timespan

  • **Posted**

    • <a href="ref:post_getfeehistory" target="_blank">Get Fee History</a> — Returns all posted fees within a timespan.

  • **Pending** — These endpoints also return the transaction that triggered the fee:

    • <a href="ref:post_getaccountoverview" target="_blank">Get Account Overview</a>

    • <a href="ref:post_getpendingfees" target="_blank">Get Pending Fees</a>

#### Holds

To show holds on an account, you can call <a href="ref:post_getholdhistory" target="_blank">Get Hold History</a>, which displays holds that you created with the <a href="ref:post_createhold" target="_blank">Create Hold</a> endpoint.