Acquiring Data Dictionary
The Highnote Acquiring Data Dictionary provides all the data available for querying your payment transactions, items, and orders.
The queries and objects below demonstrate how you can construct on-demand reports and generate metrics as needed.
This section lists the data tables and associated fields available to query your Highnote data.
The payment_transaction_event table is mutable and always displays the current state.
Use the following fields to query your Payment Transactions.
| Data Field | Data Type | Description |
|---|---|---|
| payment_transaction_event_id | String | Unique key identifying each event in a payment's lifecycle (e.g., authorization, capture, refund, payout) |
| payment_id | String | Unique ID of the parent payment that ties together all lifecycle events from initial authorization through final settlement |
| payment_transaction_step_id | String | Unique ID of a processing step that records the network response and outcome (e.g., approved, declined) at each stage |
| payment_credential_id | String | Unique ID of the payment credential (card, token, or network token) used for the transaction |
| brand | String | Card brand name |
| step_type_code | String | Code of the transaction step type |
| step_type_value | String | Human-readable name of the transaction step type (e.g., CARD_AUTHORIZED, CARD_CAPTURED, CARD_REVERSED, CARD_CREDITED, CARD_VERIFIED) |
| event_type_code | String | Code of the payment transaction event type |
| event_type_value | String | Value of the payment transaction event type |
| refund_indicator | Boolean | Indicates whether this event is a refund or not |
| merchant_settlement_account_id | String | Unique ID of the financial account where merchant funds are deposited after settlement |
| merchant_id | String | Unique ID assigned by Highnote to identify the merchant entity |
| merchant_acceptor_id | String | Card acceptor ID (ISO 8583) that identifies the merchant to the card network |
| network_merchant_id | String | Unique ID assigned by the card network (Visa, Mastercard) for transaction routing |
| acquirer_reference_number | String | Reference number sent to the card network to uniquely identify the capture for reconciliation |
| processing_code | String | ISO 8583 processing code that indicates the transaction type and account type (e.g., purchase, refund, cash advance) |
| processing_code_name | String | Human-readable name of the ISO 8583 processing code |
| transaction_amount_signed | Integer | Amount of the transaction event requested by the cardholder, in the local currency of the acquirer or source location of the transaction (in minor units, signed) |
| transaction_amount_currency_code | String | ISO 4217 code representing the currency of the transaction amount |
| settlement_amount_signed | Integer | Amount of the transaction event in the settlement's currency (in minor units, signed). Usually the same as transaction_amount_signed |
| settlement_amount_currency_code | String | ISO 4217 code representing the currency of the settlement amount |
| interchange_fee_amount_signed | Integer | Fee charged by the card network (issuer) for processing the transaction (in minor units, signed) |
| interchange_fee_amount_currency_code | String | ISO 4217 code representing the currency of the interchange fee amount |
| platform_fee_amount_signed | Integer | Fee charged by the platform for this transaction, also called merchant discount fee (in minor units, signed) |
| platform_fee_amount_currency_code | String | ISO 4217 code representing the currency of the platform fee amount |
| dispute_chargeback_fee_amount_signed | Integer | Fee associated with a dispute or chargeback transaction (in minor units, signed) |
| dispute_chargeback_fee_amount_currency_code | String | ISO 4217 code representing the currency of the dispute chargeback fee amount |
| fee_amount_signed | Integer | Total fee amount for the transaction event (in minor units, signed) |
| fee_amount_currency_code | String | ISO 4217 code representing the currency of the fee amount |
| net_disbursement_amount_signed | Integer | Net disbursed amount to the merchant's settlement account (settlement_amount_signed + fee_amount_signed) |
| dispute_amount_signed | Integer | Amount being disputed in a chargeback or dispute case (in minor units, signed) |
| dispute_amount_currency_code | String | ISO 4217 code representing the currency of the disputed amount |
| batch_job_id | String | Unique ID of the batch job that processed the payout and initiated fund transfers |
| original_network_transaction_id | String | Network transaction ID of the original transaction |
| processor_code | String | Code of the processor in which this transaction was processed |
| network_response_code | String | Highnote's normalized response code |
| program_id | String | Unique ID of the acquiring program that groups products under a sponsor bank relationship |
| program_name_snapshot | String | Snapshot of the acquiring program name at the time when the transaction event is processed |
| product_id | String | Unique ID of the acquiring product that defines merchant pricing and processing rules |
| product_name_snapshot | String | Snapshot of the acquiring product name at the time when the transaction event is processed |
| payment_order_id | String | Unique ID of the payment order containing items and distribution instructions for the transaction |
| payout_id | String | Unique ID of the payout batch that groups disbursements processed together |
| receiving_account_id | String | Unique ID of the external bank account receiving the payout funds |
| transfer_id | String | Unique ID of the actual fund transfer moving money to the merchant's bank account |
| disbursement_transaction_id | String | Unique ID linking this event to the merchant disbursement that transferred funds to the settlement account |
| network_settlement_date | Date | Date that banks use to settle the card transaction amounts |
| platform_date | Date | Date when the transaction was settled on the platform, with a cutoff time of 8 PM Eastern Time (ET) |
| total_installment_amount_signed | Integer | Total amount for all installment payments combined (in minor units, signed) |
| total_installment_amount_currency_code | String | ISO 4217 code representing the currency of the total installment amount |
| number_of_installments | Integer | Total number of installment payments for the transaction (e.g., 4, 6, 12) |
| installment_amount_signed | Integer | Amount of each individual installment payment (in minor units, signed) |
| installment_amount_currency_code | String | ISO 4217 code representing the currency of the installment amount |
| installment_payment_number | Integer | Current installment number in the sequence (e.g., 1, 2, 3...) |
| installment_frequency_code | String | Code of the frequency of installment payments. |
| first_installment_date | Date | Date of the first installment payment |
| total_amount_funded_signed | Integer | Cumulative total amount funded so far across completed installments (in minor units, signed) |
| total_amount_funded_currency_code | String | ISO 4217 code representing the currency of the total amount funded |
| single_auth_installment_ind | Boolean | Indicates whether this is a single authorization with multiple captures (true) or multiple authorizations for each installment (false) |
| create_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the payment transaction event record was created |
| update_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the payment transaction event record was last updated |
The payment_instruction table is mutable and always displays the current state.
Use the following fields to query your Payment Instructions.
| Data Field | Data Type | Description |
|---|---|---|
| payment_instruction_item_id | String | Unique key identifying a fund distribution instruction for a specific order item |
| payment_instruction_group_id | String | Unique ID grouping related payment instructions that should be processed together |
| payment_order_id | String | Unique ID of the payment order containing items and distribution instructions |
| payment_order_item_list_id | String | Unique ID of a line item within the payment order (e.g., product, tax, shipping) |
| catalog_item_id | String | Unique ID of the catalog item from the merchant's product catalog |
| order_item_name | String | Name of the order item |
| order_item_description | String | Description of the order item |
| order_item_quantity | Decimal | Quantity of the order item |
| order_item_amount_signed | Integer | Amount of the order item |
| order_item_amount_currency_code | String | ISO 4217 code representing the currency of the order item amount |
| order_total_amount_signed | Integer | Total amount of the order |
| order_total_amount_currency_code | String | ISO 4217 code representing the currency of the order total amount |
| instruction_percent | Decimal | Payment instruction percentage |
| instruction_amount_signed | Integer | Payment instruction amount |
| financial_account_id | String | Unique ID of the financial account receiving the disbursed funds |
| create_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the payment instruction item record was created |
| update_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the payment instruction item record was last updated |
The payment_order_item table is mutable and always displays the current state.
Use the following fields to query your Payment Orders.
| Data Field | Data Type | Description |
|---|---|---|
| payment_order_id | String | Unique ID of the parent payment order containing this item |
| payment_order_item_list_id | String | Unique key identifying a line item within the payment order (e.g., product, tax, shipping) |
| payment_instruction_group_id | String | Unique ID grouping related payment instructions for this item |
| order_item_name | String | Name of the order item |
| order_item_description | String | Description of the order item |
| order_item_quantity | Decimal | Quantity of the order item |
| order_item_amount_signed | Integer | Amount of the order item |
| order_item_amount_currency_code | String | ISO 4217 code representing the currency of the order item amount |
| order_total_amount_signed | Integer | Total amount of the order |
| order_total_amount_currency_code | String | ISO 4217 code representing the currency of the order total amount |
| create_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the payment order item record was created |
| update_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the payment order item record was last updated |
The merchant_disbursement table provides disbursement amounts for merchants by product and network settlement date.
Use the following fields to reconcile merchant payouts and understand the breakdown of transaction amounts, fees, and adjustments.
| Data Field | Data Type | Description |
|---|---|---|
| disbursement_transaction_id | String | Unique key identifying a merchant payout record aggregated by product and network settlement date |
| merchant_settlement_account_id | String | Unique ID of the financial account where merchant funds are deposited after settlement |
| merchant_id | String | Unique ID assigned by Highnote to identify the merchant entity |
| network_merchant_id | String | Unique ID assigned by the card network (Visa, Mastercard) for transaction routing |
| product_id | String | Unique ID of the acquiring product that defines merchant pricing and processing rules |
| product_name_snapshot | String | Name of the acquiring product at the time of disbursement |
| program_id | String | Unique ID of the acquiring program that groups products under a sponsor bank relationship |
| program_name_snapshot | String | Name of the program at the time of disbursement |
| network_settlement_date | Date | Date on which the network settled the transactions |
| gross_transaction_amount_signed | Integer | Gross transaction amount in minor units (signed: positive=CREDIT, negative=DEBIT) |
| gross_transaction_amount_currency_code | String | ISO 4217 code representing the currency of the gross transaction amount |
| interchange_fee_amount_signed | Integer | Interchange fee amount in minor units (signed: positive=CREDIT, negative=DEBIT) |
| interchange_fee_amount_currency_code | String | ISO 4217 code representing the currency of the interchange fee amount |
| platform_fee_amount_signed | Integer | Platform fee amount in minor units (signed: positive=CREDIT, negative=DEBIT) |
| platform_fee_amount_currency_code | String | ISO 4217 code representing the currency of the platform fee amount |
| dispute_amount_signed | Integer | Disputed transaction amount for the merchant and settlement date in minor units (signed) |
| dispute_amount_currency_code | String | ISO 4217 code representing the currency of the dispute amount |
| dispute_chargeback_fee_amount_signed | Integer | Chargeback fee amount for the merchant and settlement date in minor units (signed) |
| dispute_chargeback_fee_amount_currency_code | String | ISO 4217 code representing the currency of the dispute chargeback fee amount |
| carryover_amount_signed | Integer | Disbursement carryover amount in minor units when below minimum threshold (signed) |
| carryover_amount_currency_code | String | ISO 4217 code representing the currency of the carryover amount |
| precision_variance_amount_signed | Integer | Interchange precision adjustment amount for reconciliation in minor units (signed) |
| precision_variance_amount_currency_code | String | ISO 4217 code representing the currency of the precision variance amount |
| processor_code | String | Code identifying the payment processor (e.g., VISA_DMS, MASTERCARD_DMS, MASTERCARD_SMS, MNGS, PAYROC) |
| sponsor_bank_id | String | Unique ID of the sponsor bank that facilitates the merchant's payment processing relationship |
| create_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the merchant disbursement record was created |
| update_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the merchant disbursement record was last updated |
The merchant_dispute table is mutable and always displays the current state of each dispute, including the latest stage information.
Use the following fields to query and track your merchant dispute cases through their lifecycle.
| Data Field | Data Type | Description |
|---|---|---|
| transaction_dispute_id | String | Unique key identifying a dispute case as it progresses through the chargeback lifecycle |
| financial_account_id | String | Unique ID of the financial account associated with the disputed transaction |
| merchant_id | String | Unique ID assigned by Highnote to identify the merchant entity |
| merchant_acceptor_id | String | Sub-merchant ID within a payment facilitator model |
| merchant_category_code | String | 4-digit ISO 18245 code classifying businesses by the type of goods or services they provide |
| network_case_id | String | Case ID assigned by the card network (e.g., VROL for Visa, NGOM for Mastercard) to track the dispute |
| payment_id | String | Unique ID of the parent payment that ties together all lifecycle events |
| original_transaction_capture_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | Event date of the original payment transaction step |
| original_transaction_capture_amount | Integer | Transaction amount from original payment step in minor units |
| network_code | String | Card scheme/network identifier (e.g., VISA, MASTERCARD, DISCOVER, AMEX) |
| card_bin | String | Bank Identification Number - first 6-8 digits of the payment card |
| card_last4 | String | Last 4 digits of the payment card number |
| case_type_code | String | Type of case: CHARGEBACK or INQUIRY |
| requested_amount_signed | Integer | Requested dispute amount in minor units (can be null for inquiries) |
| requested_amount_currency_code | String | ISO 4217 code representing the currency of the requested amount |
| settled_dispute_amount | Integer | Final settled dispute amount in minor units |
| settled_dispute_amount_currency_code | String | ISO 4217 code representing the currency of the settled dispute amount |
| dispute_category_code | String | Category of dispute: FRAUD, INVALID_AUTHORIZATION, PROCESSING_ERROR, CONSUMER_DISPUTE, or COMPLIANCE |
| network_reason_code | String | Network-specific reason code for the chargeback (e.g., 4837 for Mastercard) |
| network_reason_description | String | Human-readable description of the network reason code |
| stage_code | String | Current stage of chargeback lifecycle: FIRST_CHARGEBACK, REPRESENTMENT, PRE_ARBITRATION, or ARBITRATION |
| status_code | String | Current status of the dispute stage: INITIAL, IN_REVIEW, TIMED_OUT, or CLOSED |
| stage_start_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the current dispute stage began |
| stage_end_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the current dispute stage ended |
| response_due_by_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | SLA target deadline for merchant/acquirer response to the current stage |
| final_outcome_code | String | Final resolution outcome: WON, LOST, or CANCELLED |
| closed_ind | Boolean | Indicator whether the dispute case is closed |
| closed_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the dispute case was closed |
| create_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the merchant dispute record was created |
| update_timestamp | DateTime (ISO 8601: YYYY-MM-DDTHH:MM:SSZ) | UTC timestamp when the merchant dispute record was last updated |
This acquiring query library includes a selection of common Highnote queries in the Snowflake dialect. We demonstrate how to generate the following types of reports:
The queries below include a defined date range which you can edit as necessary:
To see the full data set, remove the BETWEEN condition in each query:
Foundational reports are essential for understanding the system's structure and configuration. These reports identify available accounts, ledger types, and their relationships, providing the foundational context needed to interpret all other financial reports.
The following query returns all accounts and associated ledgers.
- Query List accounts and ledgers
Transaction detail reports monitor individual transactions and their impact on account balances over time. These reports show the complete flow of funds through the system, including running balances, transaction linkages, and reconciliation details necessary for auditing and troubleshooting.
The following query returns the running balance of a settlement account, showing how each transaction affects the account balance over time.
- Query Cash Movement
The following query returns all transactions and running balances for a Product Funding account, linking each ledger entry to its corresponding payment event for reconciliation purposes.
- Query Balance Report
The following query generates a parameterized monthly ledger report for a Product Funding Account, showing all transactions and balance changes for a specified date range in reverse chronological order.
- Query Visa Product Funding
Aggregated reports consolidate transaction data into meaningful business metrics. These reports provide executive-level insights into settlement volumes, payout amounts, and platform fees across different time periods and payment brands.
The following query generates a monthly settlement report for a defined date range, summarizing completed payouts by payment brand with counts, gross amounts, merchant fees, and net settlement totals.
- Query Monthly Aggregated Invoice Report
The following query summarizes daily payout batches for a defined date range, showing the number of transactions and total amount disbursed in each payout run.
- Query Monthly Payout Report
The following query calculates the total platform fees earned from all completed payouts during a defined date range.
- Query Monthly Aggregate Fees
Distribution reports reveal how the payment system operates behind the scenes. These reports show payment routing rules, fund distribution logic, and product-level performance metrics that help optimize payment operations and understand revenue allocation.
The following query retrieves payment distribution instructions for a defined date range, showing how order amounts are split across different financial accounts based on percentage-based routing rules.
- Query Distribution Payment Detail Report
The following query analyzes cleared transactions by payment brand and product/item type for a defined date range, showing total sales amounts for each combination.
- Query Settled Cleared Transactions by Card Brand and Item