> ## Documentation Index
> Fetch the complete documentation index at: https://nextgen-docs.enfuce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction file schema

> Columns, data types and allowed values in the Data Files Transaction file, and how the SCA exemption reason is determined.

The Transaction file contains events related to transactions, authorisation requests, transaction advice and clearing. Each row represents one transaction event, and all transaction event types are delivered in this one file. For file naming, format and conventions, see [Working with the files](https://nextgen-docs.enfuce.com/guides/data/data-files/working-with-files.md).

| Column | Data type | Allowed values / format | Description |
| :- | :- | :- | :- |
| `event_type` | string | `transaction_event_request`, `transaction_event_advice`, `transaction_event_notification`, `anti_fraud_advice_created`, `transaction_cleared` | Type of transaction event represented by the row. All transaction event types are included in this file. |
| `event_created_at` | datetime | ISO 8601 datetime | Date and time when the event occurred or was emitted. |
| `transaction_event_id` | UUID | UUID | Unique system-generated ID assigned to the event in the payment processing workflow. |
| `reference_transaction_event_id` | UUID | UUID / empty | Reference transaction event ID, applicable for `VOID_AUTHORIZATION`. |
| `transaction_id` | UUID | UUID | Enfuce-generated unique ID assigned to the card transaction. Events for the same card payment share the same transaction ID. |
| `message_category` | string | `INITIAL_AUTHORIZATION`, `INCREMENTAL_AUTHORIZATION`, `DECLINED_AUTHORIZATION`, `ADJUSTMENT`, `REVERSAL`, `BALANCE_INQUIRY`, `PIN_MANAGEMENT`, `PIN_MANAGEMENT_REVERSAL`, `FINANCIAL`, `FINANCIAL_ADDENDUM`, `FEE_COLLECTION`, `RECONCILIATION`, `PURGE_AUTHORIZATION`, `VOID_AUTHORIZATION`, `CHARGEBACK`, `CHARGEBACK_REVERSAL`, `REPRESENTMENT`, `REPRESENTMENT_REVERSAL`, `DOCUMENT_REQUEST`, `ACCOUNT_STATUS_INQUIRY` | Message category sent in the transaction event webhook. |
| `message_function` | string | `REQUEST`, `ADVICE`, `NOTIFICATION`, `ACCOUNT_STATUS_INQUIRY` | Message function of the transaction event. |
| `clearing_status` | string | `CLEARED`, `PARTIALLY_CLEARED` | Status of the transaction clearing. |
| `card_id` | UUID | UUID | Enfuce-generated unique ID of the card used for the transaction. |
| `card_expiration_year` | integer | YYYY | Expiration year of the card as received in the scheme message. |
| `card_expiration_month` | integer | MM | Expiration month of the card as received in the scheme message. |
| `card_sequence_number` | integer | Integer, minimum 0 | Card sequence number as received in the scheme message. |
| `card_account_id` | string | 1–36 characters; letters, numbers, hyphen | Ledger-provided account ID associated with the card. |
| `card_cardholder_id` | UUID | UUID | Unique ID of the cardholder associated with the card. |
| `card_groups` | string | List of group IDs in a single column, separated by a semicolon | Parent card groups associated with the card. The underlying value is an array, delivered as a string. |
| `card_application_selection` | string | `DEBIT`, `CREDIT` | Type of card application used for the transaction. |
| `merchant_id` | string | String | ID assigned to the card acceptor, such as a merchant or bank. |
| `merchant_name` | string | String | Merchant name as received from the card scheme. For ATMs, this can be a street address or bank branch number. |
| `merchant_city` | string | String | City where the transaction occurred or where the merchant is registered. |
| `merchant_country` | string | ISO 3166-1 alpha-3 country code | Country where the transaction occurred or where the merchant is registered. |
| `merchant_zip_code` | string | String | Merchant postal code. |
| `merchant_address` | string | String | Merchant street address. |
| `merchant_category_code` | string | String | Merchant category code as per the card scheme classification, based on the type of business or service the merchant provides. |
| `merchant_category_description` | string | String | Description of the merchant category code. |
| `merchant_category_group` | string | String | Merchant category code group as received from the scheme. |
| `merchant_terminal_id` | string | String | Unique ID assigned to the terminal used by the merchant. |
| `merchant_sub_merchant_id` | string | String | Sub-merchant ID, used when the merchant ID is not sufficient to identify the merchant. |
| `merchant_partial_approval_capable` | boolean | `true`, `false` | Indicates whether the merchant can accept partial approval of an amount. |
| `merchant_acquirer_id` | string | String | Unique ID assigned to the financial institution acting as the merchant acquirer. |
| `merchant_acquirer_country` | string | ISO 3166-1 alpha-3 country code | Country of the merchant acquirer. |
| `merchant_acquirer_reference_data` | string | String | Data supplied by the acquirer in an acquirer-originated message. |
| `transaction_auth_code` | string | 6 digits | Enfuce-generated authorisation code returned to the merchant when the authorisation is approved. |
| `transaction_auth_validity` | integer | Integer | Number of days the authorisation is valid. |
| `transaction_billing_amount_amount` | number | Number | Transaction amount in the currency of the ledger account associated with the card. Includes any issuer transaction fees applied. |
| `transaction_billing_amount_currency` | string | ISO 4217 currency code | Currency of the billing amount. |
| `transaction_transaction_amount_amount` | number | Number | Transaction amount in the local currency of the acquirer or merchant. |
| `transaction_transaction_amount_currency` | string | ISO 4217 currency code | Currency of the transaction amount. |
| `transaction_settlement_amount_amount` | number | Number | Amount transferred between the acquirer and issuer. Equal to the transaction amount, expressed in the settlement currency. |
| `transaction_settlement_amount_currency` | string | ISO 4217 currency code | Currency of the settlement amount. |
| `transaction_acquirer_transaction_fee_amount_amount` | number | Number | Fee charged by the acquirer for transaction activity. |
| `transaction_acquirer_transaction_fee_amount_currency` | string | ISO 4217 currency code | Currency of the acquirer transaction fee amount. |
| `transaction_cardholder_verification_methods` | string | `PIN_VERIFIED_BY_CARD`, `PIN_VERIFIED_BY_ISSUER`, `WALLET`, `THREE_DS`, `BIOMETRIC`, `SIGNATURE`, `NO_VERIFICATION` | Methods used for verifying the cardholder. The underlying value is an array, delivered as a string, with the values in a single column separated by a semicolon. |
| `non_sca_reason` | string | Outside EEA, Contactless Low Value, Unattended Terminal, Recurring Transaction, Low Value Transaction, Merchant Initiated Transaction, Other | Reason why the cardholder was not strongly authenticated. Where more than one exemption applies, the value follows the [prioritisation of SCA exemptions](#prioritisation-of-sca-exemptions). |
| `transaction_retrieval_reference_number` | string | String | Merchant- or acquirer-generated transaction reference number. |
| `transaction_card_entry_mode` | string | `CHIP`, `CHIP_CONTACTLESS`, `MAGNETIC_STRIPE`, `MANUAL_ENTRY`, `WALLET_CONTACTLESS`, `ECOMMERCE`, `WALLET_ECOMMERCE`, `CREDENTIALS_ON_FILE`, `UNKNOWN` | How the card credentials were captured. |
| `transaction_cardholder_present` | boolean | `true`, `false` | Indicates whether the cardholder was physically present during the transaction. |
| `transaction_card_present` | boolean | `true`, `false` | Indicates whether the card was present at the point of service. |
| `transaction_merchant_initiated` | boolean | `true`, `false` | Indicates whether the transaction was merchant initiated or recurring. |
| `transaction_transaction_date_time` | datetime | Local date-time | Date and time in the time zone where the transaction occurred. |
| `transaction_original_transaction_id` | string | String | Original transaction ID, present for recurring transactions. |
| `transaction_transaction_type` | string | `RETAIL`, `ATM`, `UNIQUE`, `CASH_DISBURSEMENT`, `CREDIT`, `ORIGINAL_CREDIT`, `BALANCE_INQUIRY`, `P2P_DEBIT`, `P2P_CREDIT`, `PIN_CHANGE`, `PIN_UNBLOCK`, `CASHBACK`, `CONVENIENCE_CHECK`, `BALANCE_TRANSFER`, `REVERSAL`, `AFT` | Transaction type. |
| `transaction_approved_amount_amount` | number | Number | Amount approved at the current payment processing stage. May be reduced at later stages. Includes any issuer transaction fees applied. |
| `transaction_approved_amount_currency` | string | ISO 4217 currency code | Currency of the approved amount. |
| `transaction_processed_date_time` | datetime | ISO 8601 datetime | Time when the transaction was processed by Enfuce. |
| `transaction_original_amount_amount` | number | Number | Previous amount in a financial message that has been corrected, in transaction currency. |
| `transaction_original_amount_currency` | string | ISO 4217 currency code | Currency of the original amount. |
| `transaction_issuer_fee_cash_amount` | number | Number / empty | Cash fee charged by the issuer, in the cardholder billing currency. Empty when no cash fee applies. |
| `transaction_issuer_fee_atm_amount` | number | Number / empty | ATM fee charged by the issuer, in the cardholder billing currency. Empty when no ATM fee applies. |
| `transaction_issuer_fee_markup_amount` | number | Number / empty | Markup fee charged by the issuer, in the cardholder billing currency. Empty when no markup fee applies. |
| `transaction_issuer_fee_currency` | string | ISO 4217 currency code | Currency of the issuer fee amounts on the row. |
| `transaction_reconciliation_date` | date | ISO date | Clearing system processing date in the local time zone of the clearing system. |
| `transaction_reconciliation_cycle` | string | String | Reconciliation period within a reconciliation date. |
| `transaction_interchange_fee_amount` | number | Number | Interchange calculated by the scheme for the transaction. |
| `transaction_interchange_fee_currency` | string | ISO 4217 currency code | Currency of the interchange fee amount. |
| `transaction_interchange_fee_direction` | string | `CREDIT`, `DEBIT`, `UNKNOWN` | Indicates whether the interchange fee amount is a credit or a debit for the cardholder. |
| `transaction_exchange_rate_ecb` | number | Number / empty | European Central Bank exchange rate for the transaction. Empty when both currencies are the same. |
| `transaction_clearing_status` | string | `CLEARED`, `PARTIALLY_CLEARED` | Clearing status of the transaction. |
| `transaction_partial_clearing_applied` | boolean | `true`, `false` | Indicates whether the transaction was cleared in a single operation. |
| `transaction_response_code` | string | 2 characters; numbers or uppercase letters | Response to the authorisation, indicating whether it was approved or declined. Alphanumeric codes are supported, for example `N7`. |
| `token_id` | string | String | Identifier of the token associated with the card. |
| `token_wallet_identifier` | string | `MASTERPASS`, `APPLE_PAY`, `GOOGLE_PAY`, `SAMSUNG_PAY`, `REMOTE_COMMERCE_PROGRAMS` | Specific digital wallet associated with the token. |

## SCA exemption reason

The `non_sca_reason` column holds the reason why the cardholder was not strongly authenticated. The reportable categories are:

* Outside EEA
* Contactless Low Value
* Unattended Terminal
* Recurring Transaction
* Low Value Transaction
* Merchant Initiated Transaction
* Other

### Prioritisation of SCA exemptions

More than one exemption can apply to the same transaction. Enfuce uses a defined prioritisation to decide which exemption to report, checking each condition in order and reporting the first that applies:

1. If the transaction was strongly authenticated (SCA), no exemption reason is reported.
2. If it was initiated outside the EEA: Outside EEA.
3. If it is a contactless low value transaction: Contactless Low Value.
4. If it was initiated at an unattended terminal: Unattended Terminal.
5. If it is a recurring transaction: Recurring Transaction.
6. If it is a low value transaction: Low Value Transaction.
7. If it is a merchant initiated transaction: Merchant Initiated Transaction.
8. If none of the above applies: Other.