Athia Data Dictionary
This is the reference for the data Athia reasons over: the fields, their types, and why each one matters to the agents and dashboards that consume it. Use it to map your own schema onto Athia's model when you deliver data yourself, and to settle disagreements about why a figure in Athia differs from a figure in your own reporting.
Core reference and use-case dictionaries
The dictionary works at two levels. Field Reference defines the core entities every Athia deployment uses, whatever you are optimizing: transactions and attempts, orders, instruments and customer, money movement, cost, risk and disputes. Each use case then adds the fields specific to it, on its own page, alongside those core entities.
| Page | What it covers | Data points |
|---|---|---|
| Field Reference | The core entities every deployment uses: attempts, orders, instruments, money movement, cost, risk and disputes | Core |
| Acceptance Rate Optimization | Maximize authorization success: diagnose declines, route smarter, retry intelligently | 50 |
| Subscriptions & Recurring Payments | Protect MRR: recover failed charges, manage card lifecycle, predict churn | 42 |
| Payment Reconciliation | Tie every transaction from order to bank deposit: fees, payouts, disputes, exceptions | 59 |
| Payment Cost Optimization | Lower effective MSC: qualify for best interchange, minimize scheme fees, route for cost | 37 |
| Fraud Detection & Prevention | Score transactions, identify accounts, attack patterns, abusers | 56 |
You do not need every use case's fields. Send what the use cases you care about require.
How to read this dictionary
The field names here are the names Athia uses internally, and the ones to fall back on when the choice is yours. They are not a delivery contract. Send what your systems already produce, under the names they already use, and Athia maps it on ingest.
Three things still have to be true:
- The concept is present. A name Athia does not recognize can be mapped. A field you never send cannot.
- The values are usable. Populated, consistently typed, and meaning the same thing on every row.
- The mapping is stated. Your Athia team agrees it with you during setup. That is where any question about which of your fields is which gets settled.
Conventions:
- Concepts that providers report differently, and so carry no single name, appear by description rather than a field name.
- Timestamps are ISO 8601 in UTC throughout.
- Amounts: where you deliver data yourself, convert minor units to decimal first. Scale by the currency's ISO 4217 exponent rather than always dividing by 100. The exponent is 0 for CLP, COP and JPY, whose amounts are already whole. On provider Connections, Athia normalizes units on ingest.
- Not every entity applies to every business. A minimum set is required for validation to pass. See Field availability below.
- Each use-case page rates every field Full, Partial, Limited or Not available. That rating is the fastest way to see what a use case can and cannot answer from your stack.
The field-by-field definitions for the core entities, every table, type and note, live on Field Reference.
| Concept | Name in the core reference | Name on the use-case pages |
|---|---|---|
| Transaction or attempt identifier | payment_transaction_id | transaction_id, txn_id, gateway_txn_id, attempt_id |
| Order identifier | order_id | order_id |
| Processor | psp_name | processor_id |
| Decline code | psp_error_code | gateway_decline_code, network_decline_code, issuer_response_code, acquirer_response_code, decline_code_raw |
| Decline message | psp_error_message | decline_message |
| Decline classification | Derived by Athia | decline_type, decline_code_canonical, retry_eligible |
| Retry link | order_id plus retry_sequence | parent_txn_id, original_txn_id, retry_attempt_number |
| Attempt amount | payment_amount | amount, capture_amount |
| Order amount | order_total_amount | order_amount |
| Currency | currency_code | currency, order_currency, presentment_currency |
| Settlement currency | Settlement currency, defined under Money movement. Not currency_code | settlement_currency |
| Timestamp | payment_timestamp | auth_timestamp, timestamp_ms |
| Status | payment_status | status |
| Card BIN | card_bin | BIN |
| Last four | last_four_digits | pan_last4, card_last4 |
| Card expiry | expiry_date | card_expiry |
| Customer | user_id | customer_id |
| Channel | order_channel | channel |
| Merchant category code | mcc | mcc |
| 3DS outcome | threeds_outcome | threeds_version, eci |
| AVS result | avs_result | avs_result |
| CVV result | cvv_result | cvv_result |
| Settlement identifier | Settlement or payout identifier | settlement_id, payout_id |
| Phone | phone | phone_e164 |
| Address | address | billing_address, shipping_address |
Where a concept is listed by description rather than a single name, send it under whatever name your source uses and agree the mapping with your Athia team.
Field availability
No provider supplies every field. Athia works with what it receives, and after the first load reports which fields arrived, which are partially populated and which are absent, so you can decide whether to fill a gap from another source. Two absences change what Athia can do more than any others.
| Missing | Consequence |
|---|---|
Decline code and reason (psp_error_code, psp_error_message) | Declines can be counted but not explained. Recoverable declines cannot be identified, so retry optimization has nothing to learn from |
The link between an attempt and its retries (order_id on every attempt, plus retry_sequence) | Every attempt looks like a separate order. Acceptance is understated, volume overstated, and first-attempt against final acceptance cannot be calculated |
Availability is also a matter of when, not only whether a provider supplies a field. A field that only comes into existence after a settlement cycle closes cannot answer a question about this morning, however often Athia polls the source. In practice, cost per approved transaction and every reconciliation figure lag authorization and decline figures by the provider's own settlement and statement cycle, so reading them side by side for the same day compares a settled number against an open one and will mislead you.
Updated about 18 hours ago