Mapping Transactions Within Your System

This guide provides suggestions for creating unique mapping identifiers for the transactions in your records.

As you store your own record of transactions—building off the Events API, Auth API, or RDFs and CDFs, for example—Galileo recommends that you have a way to map authorizations in your database to their respective settlements. With this mapping your customers can see authorized (pending) transactions in a separate list from settled (posted) transactions. See Transaction History for more information. Furthermore, you will need a way to differentiate transaction identifiers from different Galileo sources in your own databases.

Authorization identifiers

For each card network that you implement, Galileo creates an authorizations table. (See Networks for more information.) These are the possible authorizations tables that can be created:

  • Mastercard Banknet (credit)
  • Mastercard Maestro/Cirrus (debit)
  • Visa (credit, Interlink, Plus)
  • Allpoint
  • STAR (MoneyPass, Presto)
  • Discover
  • Pulse

Each authorizations table has auth_id as the primary key (unique identifier for a row in the table). The tables are populated independently as the transactions come in from the networks, and the rows are numbered sequentially, so it is possible for a transaction in one table to have the same auth_id as a transaction in another table. For example, if there are at least 300 transactions in each of the tables, then auth_id: 300 could refer to a Mastercard, Maestro, Visa, Allpoint, STAR, Discover or Pulse transaction.

📘

Note

The Visa and Star tables include all transactions from their respective subnetworks, so a transaction that comes in over Visa credit rails will never have the same auth_id as an Interlink or Plus transaction. Likewise, a Star transaction will never have the same auth_id as a MoneyPass or Presto transaction.

Authorization mapping

For your system, create one designator per authorizations table. (Consult the Network Codes enumeration to see Galileo network identifiers.) You could use a single-letter designator such as M for Mastercard (credit) and V for all of the Visa subnetworks, or you could use a spell-out such as mccredit, mcdebit, visa, or allpoint. You can combine the auth_id and your network identifier in any way that makes sense to you, for example:

  • visa33333
  • Disc_33333
  • 33333V
  • M-33333
  • 33333_mcdebit

Example authorization mapping

This example assumes that you are mapping network: V to visa and network: P to mc_debit.

You receive an Authorization Event message with these values:

  • type: auth
  • amount: -50
  • network: V
  • auth_id: 44444

Then you receive another Authorization Event message with these values:

  • type: auth
  • amount: -50
  • network: P
  • auth_id: 44444

Later, you receive a Settlement Event message with these values:

  • type: setl
  • amount: -50
  • network: V
  • auth_id: 44444

In your database the transactions might look like this:

TypeAmountMapping identifier
auth-50visa_44444
auth-50mc_debit_44444
setl-50visa_44444

Because the visa_44444 auth entry also has a settlement entry with the same identifier, you can display that transaction as settled, whereas the mc_debit_44444 auth has no corresponding settlement, so you would display it as pending.

Mapping non-card-network transactions

Transactions that do not take place over card-network rails have their own tables, and each table has an ID that is unique only to that table. These are the non-network transaction tables with their primary key (identifier) field names and their two-letter activity type. (For information on activity types, see Classifying transactions in the About Transactions guide.)

TableIdentifierActivity type
Adjustmentsadj_idAD
Paymentspmt_idPM
Feesfee_idFE
Holdshold_idTH
ACHtrans_id*PM or AD
Billpaybillpay_id**AD

* ACH transactions have two entries: one in the ACH table and one in either the payments or adjustments table, depending on how the funds move.
** Billpay transactions have two entries: one in the billpay table and one in the adjustments table.

If each table has at least 300 transactions, then adj_id: 300 and pmt_id: 300 would collide with auth_id: 300 in many contexts, such as in the AUTHORIZATION CODE field of the Posted Transactions RDF or in your database. To differentiate between these transaction identifiers, you can use the activity type (act_type) field or a short descriptor:

  • TH_88888
  • 88888FE
  • AD88888
  • 88888-PM
  • 88888-ach
  • billpay_88888

Reconciliation with the RDFs

Consult the table below to see how the fields discussed in this guide correspond to fields in the RDFs. For an explanation of the Activity type + transaction type column, see Classifying transactions in the About Transactions guide.

 Authorization IDNetworkActivity type + transaction typeSource ID
RDFsAUTHORIZATION CODENETWORK CODETRANSACTION CODE/TYPE*SOURCE ID**
Auth APIauth_idnetwork + subnetworkauth_type + subnetwork§auth_id
Authorization Eventsauth_idnetworkact_type + otypeauth_id
Settlement Eventsauth_idnetworkact_type + otypeauth_id
Transaction Eventsact_type + otypesource_id§§
Program API responsesauth_idnetwork_idtrans_codesource_id

* The Authorized Transactions RDF has a field called TRANSACTION CODE that is not the same as TRANSACTION CODE/TYPE in the Posted Transactions RDF. See Authorization Types for values in the TRANSACTION TYPE field.

** SOURCE ID is a custom field that you must request for the RDFs.

§ See Activity type and transaction type in the Galileo system in the About Transactions guide for instructions on how to derive the activity category from these fields.

§§ The source ID maps to the individual transaction-type identifier, such as adj_id for adjustments or pmt_id for payments.

‡ The source_id maps to different identifiers depending on which endpoint retrieves the data, as shown in this table:

Transaction ID labelEndpoint
pmt_idGet Payment History
auth_idGet Authorization History
ach_trans_idGet Deposit History
ach_transaction_idGet ACH Transaction History
hold_idGet Hold History
billpay_transaction_idGet Bill Payment History

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