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 and Auth API, 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.

Galileo generates numeric identifiers (auth_id) that are unique within each subnetwork (with some exceptions, explained in Network identifiers in authorizations, so it is possible for two unrelated authorizations to have the same auth_id) if one authorization is from Visa and the other is from Mastercard, for example. To accurately map authorizations and settlements, Galileo recommends that you create a mapping identifier for each transaction that is a combination of the auth_id plus the subnetwork.

Consult the table below to see how Galileo identifies card subnetworks across Galileo systems. Create for yourself one designator per subnetwork to apply to all transactions coming from that subnetwork, for example: visa, V, MD, mdebit, Disc.

📘

Note

This table shows all of the possible subnetworks, but you will use only a subset of them, according to your chosen card networks. (See Networks for more information.) Keep in mind that in some cases a card that explicitly belongs to one network might have its transactions transmitted on another network: for example, a Visa card transaction could arrive at Galileo over a Mastercard network, depending on merchant setup and other factors.

The second row of this table shows the field that contains the network code or text. For example, in the Auth API, the subnetwork field contains Visa PLUS for the Visa Plus network, whereas in the Events API, Visa Plus is represented as network: E, in the responses to the Program API it's network_code: Z, and in the RDFs it's NETWORK CODE Z.

NetworkAuth APIEvents APIProgram APIRDFs
 subnetworknetworknetwork_codeNETWORK CODE
VisaVisaVVV
Visa InterlinkVisa InterlinkIII
Visa PlusVisa PLUSEZZ
MastercardMastercard BanknetMMM
CirrusMastercard Debit SwitchPCC
MaestroMastercard Debit SwitchPPP
DiscoverDiscoverDDD
AllpointAllpointAAA
STARStarSSS
PrestoStar PrestoRSS
MoneyPassStar MoneyPassOSS
PulseDiscoverBBB

Network identifiers in authorizations

When Galileo sends an Authorization Event message for the Visa or STAR networks, the network field will contain the network, not the subnetwork, whereas for the Settlement Event message the subnetwork is identified. For example, an auth message that belongs to the Visa Plus subnetwork would contain network: V and for the corresponding setl it contains network: Z. You may want to create a lookup table to identify networks V, I and Z as Visa networks, for example. There will be no collisions among the identifiers for Visa, Visa Plus and Visa Interlink subnetworks, nor among the STAR, STAR Presto and STAR MoneyPass subnetworks.

On the other hand, Mastercard Banknet (M) and Mastercard Debit (P) are always communicated as separate networks, and the identifiers are generated separately.

Authorization mapping

Use the auth_id field in Authorization and Settlement Events, the Auth API, and Program API responses to finish constructing the identifier. You can combine the authorization identifier and your network identifier in any way that makes sense to you, for example:

  • visa33333
  • Disc_33333
  • 33333V
  • MD_33333
  • 33333_mdebit

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 Events 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 cannot be mapped to authorizations and so they do not have an auth_id, but you still might want to give them a unique identifier in your database for other mapping purposes such as reconciliation with the RDFs.

Galileo generates a numeric identifier for these transactions that is unique within the transaction type—payments, adjustments, fees, and holds—so it is possible for a pmt_id to be the same number as a fee_id. All of these identifiers map to the source_id in other Galileo systems.

Transaction typeEvents API identifier
Adjustmentadj_id
Paymentpmt_id
Feefee_id
Holdhold_id
ACHsource_id
Bill paybillpay_id

📘

Note

The labels for these identifiers in the Events API messages may differ according to the arrangements you make with Galileo. For example, all of these identifiers could be labeled tran_id.

Because these transactions do not take place over a card network, you cannot use network identifiers to differentiate between transaction identifiers; instead, you can use the activity type (act_type) field.

Transaction typeact_type
AdjustmentAD
PaymentPM
FeeFE
HoldTH

Mapping identifiers that you create for these transactions might look like this:

  • TH_88888
  • 88888FE
  • AD88888
  • 88888-PM

Reconciliation with the RDFs

Consult the table below to see how the fields discussed in this guide correspond to fields in the RDFs.

 Authorization IDNetworkActivity type + transaction typeSource ID
RDFsAUTHORIZATION CODENETWORK CODETRANSACTION CODE*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 Posted Transactions RDF has a field called TRANSACTION CODE/TYPE that is not the same as TRANSACTION CODE in the Authorized Transactions RDF. See Transaction codes in the About Transactions guide for more information and also the Transaction Types enumeration to see some of the possible values for these fields.

** 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 the Raw Data Files (RDFs) guide.


Did this page help you?