Field Reference
This is the field-level reference for the core entities every Athia deployment uses — transactions and attempts, orders, instruments and customer, money movement, cost, risk and disputes. The naming conventions and the crosswalk between the names here and the names on the use-case pages are on the parent page, Athia Data Dictionary.
Transactions and attempts
The core domain. Each payment attempt carries its own processor, outcome and decline reason.
The join keys on the edges are what make cross-provider analysis possible. Lose order_id on an attempt or the retry sequence and every attempt reads as a separate order: acceptance understated, volume overstated. A fraud decision hangs off the order and never off an attempt, which is why a blocked order sits outside acceptance rate entirely.
The join keys on the edges are what make cross-provider analysis possible, and the two that matter most are order_id on every attempt and retry_sequence, whose absence Field availability on the parent page explains.
Payment attempt
One attempt to take payment for an order, including every retry. An order with three tries has three payment attempts.
| Field | Type | Description | Why Athia needs it |
|---|---|---|---|
order_id | String | Reference to the order the attempt belongs to | Groups retries to their order |
payment_transaction_id | String | The processor's transaction identifier, unique per attempt | Attempt-level joins and deduplication |
payment_timestamp | ISO 8601 string | When the attempt was made, UTC. Use authorization time | Every trend and baseline |
payment_status | Enum | authorized, captured, denied, pending, refunded, chargedback. denied is the value for a declined attempt — what the rest of the documentation calls a decline, and the attempts that carry psp_error_code | Outcome of every attempt; the basis for acceptance rate and every funnel figure |
payment_amount | Decimal | Amount of the attempt. May differ from the order total on partial captures | Value weighting, cost per approved transaction |
currency_code | ISO 4217 | Transaction currency | Prevents cross-currency aggregation |
psp_name | String | The processor that handled the attempt | Any routing comparison, and how agents learn which processor wins |
psp_error_code | String | The processor's decline code. Failed attempts only | All decline analysis, and how agents learn which declines are worth retrying |
psp_error_message | String | Human-readable decline description | Clusters raw codes into causes |
mit_cit_reference | Enum | CIT (customer-initiated) or MIT (merchant-initiated) | The two are priced, authenticated and declined differently |
retry_sequence | Integer | Position of the attempt in its order's sequence | First-attempt against final acceptance, and retry gain |
threeds_outcome | String | Authentication result and version, where reported | Authenticated and unauthenticated attempts approve differently |
avs_result | String | Address verification response, match or no-match | Issuer behavior and fraud context |
cvv_result | String | CVV response, match or no-match. The submitted value is never collected | Issuer behavior and fraud context |
mcc | String | Merchant category code the attempt was processed under | Interchange level and issuer behavior vary by MCC |
card_bin | String | Cards only. Defined under Instruments and customer | Issuer-level and BIN-level routing analysis |
metadata | JSON | Extra context: device fingerprint, IP geography, session identifier | Signals your provider does not expose as fields |
Where your provider reports intermediate states, Athia also ingests payment events — authorization, 3DS, capture, refund and void as discrete rows rather than one final status. These answer timing questions, such as how long elapses between authorization and capture.
Order
The commercial record a payment belongs to.
| Field | Type | Description | Why Athia needs it |
|---|---|---|---|
order_id | String | Order identifier, unique per order | The join key for everything else |
order_timestamp | ISO 8601 string | When the order was placed, UTC | Order-level trends and conversion |
order_total_amount | Decimal | Total order value | Turns acceptance into revenue |
order_status | Enum | created, completed, cancelled, refunded | Commercial outcome against payment outcome |
payment_method | Enum | credit_card, debit_card, cash, wallet, bnpl | Method mix and method-level acceptance |
order_channel | Enum | web, app, call_center, kiosk | Channel comparison, and separating checkout problems from payment problems |
merchant_id | String | Brand or regional entity identifier | Multi-brand and multi-market comparison. Carries merchant_name, utc_offset and merchant_currency |
user_id | String | Defined under Instruments and customer | Repeat behavior and segmentation |
subscription_id | String | Subscription reference, recurring charges only | Renewal failure and involuntary churn |
Without utc_offset, peak hour and the daily boundary land in the wrong place across markets.
Instruments and customer
Card attributes, and the identifiers that link attempts to a person.
| Field | Type | Description | Why Athia needs it |
|---|---|---|---|
card_bin | String | Leading digits identifying issuer and product: 6 or 8 digits; 8 where the provider supplies them | Resolves issuer, brand, card product and card country against BIN reference data |
last_four_digits | String | Masked card reference, last four only | Instrument identification alongside BIN |
expiry_date | ISO 8601 string | When the stored instrument expires | Expiry-driven renewal failure |
| Fingerprint or PAR | String | The provider's stable card reference, where supplied | Recognizes one card across reissues and providers |
payment_method_id | String | Stored instrument, held as a tokenized reference | Stored-method mix and acceptance |
payment_method_type | Enum | For example credit_card, debit_card, paypal, apple_pay, pix | Method-level performance |
user_id | String | Internal user identifier. Prefer a stable UUID | Separates a first-time buyer's decline from a returning customer's |
email, phone, address | String | Optional. Deliver hashed, tokenized or generalized | Athia never requires raw personal data |
Card data is minimized to BIN plus last four. No full card number and no CVV value is collected on any path. CVV and AVS appear only as match / no-match response codes.
Money movement
What actually left and arrived, so acceptance can be reconciled against money.
| Field | Type | Description | Why Athia needs it |
|---|---|---|---|
| Refund amount and timestamp | Decimal, ISO 8601 string | Value returned and when | Net revenue, and separating refunds from disputes |
| Settlement or payout identifier | String | The payout the transaction was included in | Groups transactions to money received |
| Original transaction reference | String | Link from a settlement line to the payment attempt | Without it, settlement cannot be reconciled to authorizations |
| Settlement date | ISO 8601 string | When the payout was made | Authorization-to-cash timing |
| Gross, deductions, net settled amount | Decimal | What was billed, withheld and landed | The gap between approved and settled |
| Settlement currency and FX rate | ISO 4217, Decimal | Payout currency and the rate applied | Separates a real movement from a rate movement |
Cost
What a transaction cost to process. Acceptance alone ranks routes; only cost data says which is cheaper per approved transaction.
| Field | Type | Description | Why Athia needs it |
|---|---|---|---|
| Interchange | Decimal | Fee paid to the issuing bank, set by the network | Usually the largest cost component |
| Scheme fees | Decimal | Fees charged by the card network itself | Cost per approved transaction, downgrade detection |
| Gateway or provider margin | Decimal | Your provider's own charge | Provider-by-provider cost comparison |
| Network token fee | Decimal | Charge applied to network-tokenized transactions | Whether tokenization pays for itself |
| Chargeback fee | Decimal | Fee applied per dispute | The true cost of a dispute beyond the reversed amount |
| FX markup | Decimal | Cost of currency conversion | Cross-border route cost |
| Contracted rate card | Table | Rates, thresholds and conditions agreed with each provider | Expected against actual cost, where pricing leakage shows |
Under blended pricing your provider charges one rate absorbing interchange, scheme fees and margin, and the components cannot be separated afterward. Under interchange-plus they arrive as separate lines. Where your provider does not itemize, supply fees through the in-product cost CSV upload against the Athia template.
Risk and disputes
Fraud outcomes and the dispute lifecycle, joined back to the attempt.
| Field | Type | Description | Why Athia needs it |
|---|---|---|---|
| Fraud decision | Enum | Approve, review or decline from your fraud engine | These declines never reach a processor, so they sit outside acceptance rate |
| Fraud score | Decimal | The score behind the decision | What your rules cost you as well as what they save |
| Fraud reason or rule | String | What drove the decision | Separates a tightened rule set from a real rise in fraud |
| Dispute identifier | String | The chargeback record | Dispute rate by provider, BIN and segment |
| Original transaction reference | String | Link back to the payment attempt | Without it a dispute cannot be attributed to a route or BIN |
| Dispute reason code | String | The network reason code raised | Fraud disputes and service disputes have different remedies |
| Dispute amount and fee | Decimal | Value reversed and fee charged | True cost of a dispute |
| Dispute stage and status | Enum | Where the case stands | Open exposure against closed |
| Dispute and representment dates | ISO 8601 string | When the case was raised, answered and resolved | Response deadlines and representment win rate |
| Representment outcome | String | Won or lost after response | Whether contesting disputes is worth the effort |
Disputes are raised 30 to 180 days after the transaction, so twelve months of history is the working minimum for dispute analysis. A shorter window understates the rate, because the dispute period on recent transactions has not closed.
Related
Updated 1 day ago