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 sameauth_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:
Type | Amount | Mapping identifier |
---|---|---|
auth | -50 | visa_44444 |
auth | -50 | mc_debit_44444 |
setl | -50 | visa_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.)
Table | Identifier | Activity type |
---|---|---|
Adjustments | adj_id | AD |
Payments | pmt_id | PM |
Fees | fee_id | FE |
Holds | hold_id | TH |
ACH | trans_id * | PM or AD |
Billpay | billpay_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 ID | Network | Activity type + transaction type | Source ID | |
---|---|---|---|---|
RDFs | AUTHORIZATION CODE | NETWORK CODE | TRANSACTION CODE/TYPE * | SOURCE ID ** |
Auth API | auth_id | network + subnetwork | auth_type + subnetwork § | auth_id |
Authorization Events | auth_id | network | act_type + otype | auth_id |
Settlement Events | auth_id | network | act_type + otype | auth_id |
Transaction Events | — | — | act_type + otype | source_id §§ |
Program API responses | auth_id | network_id | trans_code | source_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 label | Endpoint |
---|---|
pmt_id | Get Payment History |
auth_id | Get Authorization History |
ach_trans_id | Get Deposit History |
ach_transaction_id | Get ACH Transaction History |
hold_id | Get Hold History |
billpay_transaction_id | Get Bill Payment History |
For more information on the RDFs, see the About RDFs and CDFs guide.
Updated 8 months ago