Issuing Data Dictionary
This section lists the data tables and associated fields available to query your Highnote data.
The code_enum_lookup table is mutable and is updated periodically.
Join this table to your queries to return specific enum values. For an example, see Query: Get ledger entry report.
| Field name | Data type | Description |
|---|---|---|
| table_name | String | Name of the database table to which the enum values correspond. Helps identify which table the enum codes belong to. |
| code_column_name | String | Name of the column within the referenced table_name that uses the enum code. Provides a direct link between the enum value and its usage in a specific column of a table. |
| code | String | Actual enum code used in the database. This is the value stored in the column specified by code_column_name in the table_name. |
| code_enum | String | Descriptive name or label representing the enum code. This human-readable description provides more context for what the code represents. |
| create_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the code enum lookup record was created. Helps track when the enum was first introduced into the system. |
| update_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the code enum lookup record was last updated. Helps with auditing and understanding the history of changes to the enum values. |
The card table is mutable and always displays the current state.
Use the following fields to query your card products.
| Field name | Data type | Description |
|---|---|---|
| card_id | String | Unique key identifying an issued payment card linked to a cardholder and financial account |
| product_id | String | Unique ID of the card product that defines card behavior, limits, and features |
| product_name_snapshot | String | Name of the card product associated with the card |
| product_type_code | String | Type of the product |
| card_network | String | Name of the network provider (Visa, Mastercard) |
| expiration_date | Date | Date that the card expires |
| last4 | String | Last 4 digits of the card |
| cardholder_party_id | String | Unique ID of the cardholder's party record containing identity and contact information |
| state | String | State of the card: UNACTIVATED, ACTIVE, SUSPENDED, TERMINATED |
| financial_account_id | String | Unique ID of the financial account linked to the card for spending and balance management |
| form_factor | String | Form of the card: PHYSICAL or VIRTUAL |
| card_profile_set_id | String | Unique ID of the card profile set that defines card design, BIN, and network configuration |
| create_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the card record was created |
| export_id | String | ID that Highnote uses to track a record's lifecycle. To facilitate data investigations, Highnote may request shared record identifiers and export_id. |
| update_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the card record last updated |
The card_revision table provides an audit trail of changes to a card.
This table captures each change made to the card table as a separate record.
The version column represents the sequential revision number of each change.
Use the following fields to query and track how a card has changed over time.
| Data Field | Data Type | Description |
|---|---|---|
| card_revision_id | String | Unique key identifying a point-in-time snapshot capturing each card state change |
| card_id | String | Unique ID of the payment card this revision belongs to |
| product_id | String | Unique ID of the card product that defines card behavior, limits, and features |
| product_name_snapshot | String | Name of the card product associated with the card |
| product_type_code | String | Type of the product |
| version | Integer | Sequential revision number indicating the order of changes |
| card_network | String | Name of the network provider (Visa, Mastercard) |
| expiration_date | Date | Date that the card expires |
| last4 | String | Last 4 digits of the card |
| cardholder_party_id | String | Unique ID of the cardholder's party record containing identity and contact information |
| state | String | State of the card: UNACTIVATED, ACTIVE, SUSPENDED, TERMINATED |
| financial_account_id | String | Unique ID of the financial account linked to the card for spending and balance management |
| form_factor | String | Form of the card: PHYSICAL or VIRTUAL |
| card_profile_set_id | String | Unique ID of the card profile set that defines card design, BIN, and network configuration |
| create_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the card revision record was created |
| update_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the card revision record was last updated |
The card_transaction_event table is mutable and always displays the current state.
Use the following fields to query your transaction feed.
| Field name | Data type | Description |
|---|---|---|
| create_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the card transaction event record was created |
| export_id | String | ID that Highnote uses to track a record's lifecycle. To facilitate data investigations, Highnote may request shared record identifiers and export_id. |
| update_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the card transaction event record was last updated |
| authorization_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the transaction was first authorized on the financial account, if applicable |
| interchange_create_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the interchange record was created |
| platform_settlement_date | Date | Date when the transaction was settled on the platform, with a cutoff of 8 PM Eastern Time (ET) |
| product_id | String | Unique ID of the card product that defines card behavior, limits, and features |
| product_name_snapshot | String | Name of the card product associated with the transaction |
| financial_account_id | String | Unique ID of the financial account linked to the card for spending and balance management |
| card_profile_set_id | String | Unique ID of the card profile set that defines card design, BIN, and network configuration |
| card_network | String | Name of the network provider (Visa, Mastercard) |
| bin_classification | String | Classification of the network BIN product type (consumer, commercial, business, etc.) |
| bin_funding_type | String | Funding type for the card program (credit, prepaid, debit) |
| account_holder_id | String | Unique ID of the account holder (person or business) who owns the financial account |
| payment_card_id | String | Unique ID of the payment card used in the transaction |
| processing_network_code | String | Card transaction network. Possible values: VNT (Visanet), MCC (Mastercard Dual Message), MDS (Maestro Single Message), PUL (PULSE), or MPS (Moneypass) |
| financial_event_id | String | Unique key identifying the financial event that triggered balance changes across ledgers |
| event_type | String | Type of card financial event, e.g., AUTHORIZE, CLEAR, REVERSE, AUTHORIZE_AND_CLEAR |
| transaction_id | String | Unique ID grouping related events (e.g., AUTH and CLEAR) that belong to the same card transaction |
| merchant_identifier | String | Identifier of the merchant |
| merchant_category_code | String | 4-digit ISO 18245 code representing retail financial services. MCCs classify businesses by the type of goods or services they provide. |
| merchant_name | String | Name of the merchant where the transaction took place |
| merchant_country | String | ISO 3166 Alpha-3 code representing the country where the card was accepted |
| card_acceptor_location | String | Location where the transaction took place. Maps to the merchantID in MerchantDetails GraphQL object. |
| issuer_response_code | Enum | Highnote response code: APPROVED, DO_NOT_HONOR, NO_CARD_RECORD |
| avs_address_response_code | Enum | Code representing the result of an address verification check |
| avs_postal_code_response_code | Enum | Code representing the result of a postal code verification check |
| cvv_response_code | Enum | Code representing the result of a card verification value (CVV) check |
| settlement_ind | Boolean | Flag identifying a settled transaction |
| approved_amount_signed | Integer | Funds approved and posted to the Highnote ledger for the transaction. Appears as responseCode in GQL response. |
| approved_amount_currency_code | String | ISO 4217 code representing the currency of the approved amount |
| surcharge_fee_amount_signed | Integer | Fee for the approved amount of each transaction event type |
| surcharge_fee_amount_currency_code | String | ISO 4217 code representing the currency of the surcharge fee amount |
| requested_amount_signed | Integer | Funds requested by the network for each transaction event type |
| requested_amount_currency_code | String | ISO 4217 code representing the currency of the requested amount |
| interchange_amount_signed | Integer | Interchange amount of the transaction. Positive for income. Negative for expense. |
| interchange_amount_currency_code | String | ISO 4217 code representing the currency of the interchange amount |
| interchange_data_availability_ind | Boolean | Indicates whether or not the interchange data is available for the transaction event |
| interchange_rate_code | String | Code provided by the card network that denotes the interchange category or rate applied to the transaction. Only available for VNT and MCC. |
| pos_terminal_type_code | String | Code representing where the payment was initiated. See PointOfServiceCategory in the API reference. |
| pos_pan_entry_mode_code | String | Code representing the method for inputting a Primary Account Number (PAN) into a POS system. This is done manually or electronically via a card reader. See PanEntryMode in the API Reference. |
| pos_card_data_input_capability_code | String | Code representing the POS terminal's card input capabilities, e.g., MAGNETIC_STRIPE means the POS terminal can read magnetic stripe cards. See CardDataInputCapability in the API Reference. |
| pos_card_presence_code | String | Code representing the presence of a card during the sale: CARD_PRESENT, CARD_NOT_PRESENT, PREAUTHORIZED_PURCHASE, UNKNOWN |
| transaction_type_code | String | Code representing the card transaction processing type from the transaction type network, e.g., 00=goods and services, 01=cash, 20=returns, etc |
| platform_transaction_category | String | Category created by Highnote to calculate Highnote TPV invoices, e.g., purchase, cash, refund, funding, payment, etc. Non-TPV records display as NOT_APPLICABLE. |
| take_rate_transaction_impact | Integer | Direction multiplier used to calculate the take rate for Highnote TPV invoices. Supported values: +1, -1, 0. |
| net_settled_transaction_impact | Integer | Direction multiplier used to calculate the net settlement for Highnote TPV invoices. Supported values: +1, -1, 0. |
| original_transaction_id | String | Unique ID of the original purchase transaction when this event is a refund or reversal. Empty if the network does not provide sufficient context. |
| issuer_settlement_date | Date | Highnote (issuer) defined settlement date, calculated using network cutoff and transaction timestamp. Date that banks use to settle the card transaction amounts. |
| risk_score | Integer | The transaction risk score provided by the respective network. Visa values are between 0-99. Matercard values are between 0-999. |
The ledger_entry table is immutable.
Use the following fields to query your account ledgers.
| Field name | Data type | Description |
|---|---|---|
| create_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the ledger entry record was created |
| export_id | String | ID that Highnote uses to track a record's lifecycle. To facilitate data investigations, Highnote may request shared record identifiers and export_id. |
| update_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the ledger entry record was last updated |
| product_id | String | Unique ID of the card product that defines card behavior, limits, and features |
| product_name_snapshot | String | Name of the card product associated with the ledger entry |
| financial_account_id | String | Unique ID of the financial account that holds funds and tracks balances |
| financial_account_name_snapshot | String | Name of the financial account associated with the ledger entry |
| transaction_id | String | Unique ID grouping related events (e.g., AUTH and CLEAR) that belong to the same card transaction |
| financial_event_type | String | Activity type of the financial event (e.g., AUTHORIZE, CLEAR, REVERSE, AUTHORIZE_AND_CLEAR) |
| financial_event_id | String | Unique ID of the financial event that triggered this ledger entry |
| ledger_entry_id | String | Unique key identifying an immutable record of a balance change (e.g., authorization hold, clearing, funding) |
| change_amount_signed | Integer | Amount by which the ledger balance changed |
| normal_balance_type | Decimal | Expected balance type of an account. Possible values are Debit or Credit. |
| balance_at_ledger_entry_signed | Integer | Balance of the account after the ledger entry |
| card_transaction_settlement_ind | Boolean | Flag identifying cleared transactions to settle at the bank |
| billing_month | Date | Month of a billed invoice, with a cutoff of 8 PM Eastern Time (ET) |
| ledger_type_code | String | Code representing the type of ledger |
| platform_transaction_category | String | Category created by Highnote to calculate Highnote TPV invoices, e.g., purchase, cash, refund, funding, payment, etc. Non-TPV records display as NOT_APPLICABLE. |
| take_rate_transaction_impact | Integer | Direction multiplier used to calculate the take rate for Highnote TPV invoices. Supported values: +1, -1, 0. |
| net_settled_transaction_impact | Integer | Direction multiplier used to calculate the net settlement for Highnote TPV invoices. Supported values: +1, -1, 0. |
| issuer_settlement_date | Date | Highnote (issuer) defined settlement date, calculated using network cutoff and transaction timestamp. Date that banks use to settle the card transaction amounts. |
| receivable_purchase_date | Date | Date when Highnote purchases receivables from the sponsor bank |
| receivable_purchase_percent | Integer | Percentage of card settlement amount to be purchased for receivables |
| receivables_purchase_ind | Boolean | Indicates that ledger entry is involved in purchasing receivables |
The interchange (IC) report based on the Highnote schema is an estimate.
The interchange (IC) amounts in the schema-based report can differ from those in the invoice.
The IC amounts in the invoice are those that the networks deposit in the bank accounts automatically. The IC amounts in the report are affected by the cut-off times Highnote uses for reporting.
The IC report based on the Highnote schema should only be used as a benchmark so you can see an estimate of what the IC could be in the invoice we provide.
Mastercard Networks Exchange (NEX) was formerly known as Mastercard Network Gateway Services (MNGS).
If issuer_settlement_date = June 10 and ET = Eastern Time, transactions have following criteria:
VISA:
- Network Raw Settlement Date: June 11
- Transactions between: June 10 @ 6 AM ET to 6/11 @ 6 AM ET
NEX - MCI, MSI, PULSE, PPE, CIR, EXI:
- Network Raw Settlement Date: June 10
- Transaction between: June 9 @ 8 PM ET to June 10 @ 8 PM ET
NEX - MoneyPass:
- Network Raw Settlement Date: June 9, Jun 10
- Transaction between June 9 @ 4 PM ET to June 10 @ 4 PM ET
When calculating Total Payment Volume (TPV), the ledger_entry table accounts for both card transactions and their adjustment.
The card_transaction_event table can be used to calculate TPV in the invoice, but it does not include any manual adjustments for card transactions.
This section includes sample Highnote queries in the Snowflake dialect. You can use them to retrieve data from Highnote's data share tables.
The following query retrieves yesterday's card issuing transactions (based on a defined time cutoff), showing detailed transaction data including interchange fees, merchant information, and card product details for reconciliation and reporting.
- Query Get Card Activity Report
The following query retrieves yesterday's card-related ledger entries (based on a defined time cutoff), showing how card transactions impact the general ledger with debits, credits, and running balances across different financial accounts.
- Query Get Ledger Entry Report