order_id

Required

The stable merchant-side record identifier for the payment event. This field gives Zahlen a deterministic identity anchor for validation, troubleshooting, and replay alignment.

response_code

Required

The canonical payment response field. This field replaces processor-specific naming as the primary signal used for response-code grouping, decline behavior analysis, recovery-rate calculation, and issuer-health alerting.

customer_id

Identifies the customer associated with the transaction. This supports cohort analysis and helps distinguish customer-level recurrence from issuer-level behavior.

subscription_id

Identifies the subscription or recurring billing relationship. This helps Zahlens recovery analysis remain aligned with subscription lifecycle behavior.

merchant

Names the merchant or merchant environment that produced the event. This helps operators interpret the data source without exposing tenant-private data across network intelligence boundaries.

merchant_id

Provides a stable merchant identifier. This is useful for multi-merchant deployments and tenant-safe aggregation controls.

attempt_number

Identifies which retry attempt generated the event. This allows Zahlen to analyze recovery behavior by attempt sequence rather than treating all attempts as equivalent.

retry_day

Identifies the retry day or recovery window associated with the event. This field supports deterministic retry-window analysis and recovery-curve interpretation.

event_timestamp

Records when the payment event occurred. This field supports timeline analysis, replay ordering, operational freshness checks, and historical comparison.

amount

Records the transaction amount in major currency units. This helps operators understand financial exposure and supports future value-weighted analysis.

currency

Records the three-letter currency code. This helps distinguish regional and currency-specific behavior and supports validation of monetary context.

bank

Identifies the issuing bank or issuer name when available. This improves operator readability and supports issuer-focused reporting.

bin

Identifies the issuer BIN or BIN prefix. This is one of the most important issuer-cohort anchors because many Zahlen investigations group behavior by issuer BIN.

country

Identifies the issuer or card country as a two-letter country code. This helps distinguish local degradation from cross-country instability.

card_brand

Identifies the card brand such as Visa or Mastercard. This helps operators separate issuer behavior from brand-specific or network-specific behavior.

authorization_id

Provides the authorization reference when available. This supports traceability between merchant systems and payment authorization records.

authorization_latency_ms

Records authorization latency in milliseconds. This can help operators identify operational slowness or infrastructure stress beyond approval or decline outcomes.

merchant_category_code

Identifies the merchant category code. This can help explain differences in authorization posture across merchant types or risk categories.

recurring_indicator

Indicates whether the event is part of recurring billing behavior. This is important because recurring authorization posture can differ from one-time payment behavior.

transaction_initiator

Identifies whether the transaction was merchant-initiated, customer-initiated, or otherwise initiated. This helps interpret issuer authorization behavior in subscription contexts.

decision_action

Records the action recommended or taken by the payment decision system. This field is useful when CSV records include Zahlen decision output or downstream operational state.

decision_state

Records the decision state associated with the event. This can contribute to recovery success interpretation when explicit recovered or final_success fields are unavailable.

payment_status

Records the payment outcome state. Zahlen can use approved-style payment_status values as one of the success sources for recovery-rate calculation.

recovered

Records whether the payment eventually recovered. This directly supports recovery-rate calculation and retry effectiveness analysis.

final_success

Records whether the lifecycle ultimately succeeded. This supports final payment success interpretation and recovery observability.

lifecycle_state

Records the subscription or payment lifecycle state. This helps operators interpret whether a record belongs to active recovery, suspension, closure, or another lifecycle phase.

test_scenario

Identifies synthetic, QA, or test-scenario records. This helps operators distinguish live operational data from controlled validation data.

Zahlen canonical CSV

This is the preferred schema. It requires order_id and response_code and may include the full issuer, retry, recovery, and lifecycle context described above.

Legacy compatibility CSV

Legacy rows may use token, issuer_bin, decline_code, attempt_number, and event_timestamp. Zahlen maps token to order_id, issuer_bin to bin, and decline_code to response_code.

Decision-output CSV

Rows that include decision_action or decision_state are interpreted as enriched Zahlen decision output. This format can support operational review because it includes decision context in addition to raw payment evidence.

External processor export compatibility

The validation layer can recognize several common export shapes and map their fields into the canonical model. This support is compatibility-oriented; the canonical documentation and operator surfaces should continue to use response_code, bin, country, and card_brand as primary terms.

order_id

order id, merchant reference, merchant_reference, merchant reference id, charge id, id, transaction id, pspreference

This mapping preserves a stable merchant-side event identity even when exports use different transaction reference labels.

response_code

response code, paymentech_code, paymentech code, decline_code, decline code, refusal reason code, failure code, reason code, status

This mapping preserves response_code as the canonical analytical signal while allowing older or external export labels to remain ingestible.

bin

bin, issuer bin, issuer_bin, bin prefix

This mapping identifies the issuer cohort used for issuer-health grouping and investigation routing.

country

country, issuer country, issuer_country, card country, country/region

This mapping supports country-level issuer behavior analysis and localized degradation detection.

bank

bank, issuer name, issuer_name, acquirer

This mapping improves operator readability and helps connect technical issuer cohorts to recognizable issuer names when available.

amount

amount, amount value, gross, value

This mapping preserves transaction value context for financial exposure analysis.

card_brand

card brand, brand, card type

This mapping supports card-brand segmentation and helps distinguish issuer behavior from network or brand-level behavior.

event_timestamp

event timestamp, created, creation date, booking date, processed at

This mapping supports timeline reconstruction, freshness analysis, and replay ordering.

authorization_id

authorization id, authorization code

This mapping preserves authorization traceability when the source system provides a reference.

merchant_category_code

merchant category code, mcc

This mapping supports risk-context interpretation by merchant category.

recurring_indicator

shopper interaction, recurring processing model

This mapping supports subscription-specific interpretation because recurring payments can behave differently from customer-initiated payments.

transaction_initiator

initiated by, initiator

This mapping helps determine whether issuer behavior relates to merchant-initiated or customer-initiated payment posture.

Use response_code as the canonical name.

All new CSV guidance should instruct operators and integration teams to provide response_code. This creates stable terminology across ingestion, results, records, alerts, and investigations.

Treat paymentech_code as a compatibility alias.

The platform may continue to recognize paymentech_code in older files or artifacts, but this field should not be used as the primary documentation term.

Preserve the original response value as text.

Response codes may include leading zeroes or non-numeric status values. Treating the field as text prevents accidental normalization that could change the operational meaning.

Interpret response codes in issuer context.

A response code has operational meaning only when evaluated alongside issuer BIN, country, card brand, retry window, and recovery outcome.

missing_required_header

This means the file does not contain the required canonical fields or a complete recognized legacy header set. Add order_id and response_code for the canonical path, or confirm that legacy uploads contain token, issuer_bin, decline_code, attempt_number, and event_timestamp.

unexpected_header

This means the file contains a header outside the allowed canonical, optional, or compatibility fields. Remove the unexpected field or map it to a supported canonical field.

missing_required_value

This means a required field is present but empty in at least one row. Populate the missing value or remove the invalid row before upload.

invalid_bin or invalid_issuer_bin

This means the BIN field contains non-digit characters. BIN values should contain only digits because they are used as issuer-cohort identifiers.

invalid_country

This means the country field is not a two-letter country code. Use ISO-style two-letter values such as US, CH, ES, or CA.

invalid_integer

This means a field such as attempt_number or retry_day contains a non-integer value. Replace text, decimals, or blank placeholders with valid integers where the field is provided.

integer_below_minimum

This means a numeric field is below the allowed minimum. attempt_number must be at least 1, and retry_day must be zero or greater when provided.

invalid_number

This means amount or authorization_latency_ms contains a value that cannot be parsed as numeric. Use standard numeric formatting without currency symbols.

number_below_minimum

This means amount or latency is below the allowed minimum. Amount and authorization latency should not be negative.

invalid_timestamp

This means event_timestamp is not a valid ISO-like timestamp. Use a timestamp such as 2026-05-27T14:10:11+00:00.

invalid_currency

This means currency is not a three-letter code. Use values such as USD, CHF, CAD, or EUR.

invalid_boolean

This means recovered or final_success contains a value outside accepted boolean forms. Accepted true values include true, t, 1, yes, and y. Accepted false values include false, f, 0, no, and n.

unrecognized_row_format

This means the row does not match canonical, legacy, or recognized compatibility formats. Start with the canonical minimal schema of order_id and response_code, then add optional fields gradually.

Canonical field names

Canonical names reduce ambiguity. When response_code, bin, country, and card_brand mean the same thing across uploads, the platform can compare results across time and replay windows.

Stable order identity

order_id gives each record a merchant-side identity anchor. This supports troubleshooting, row-level review, and deterministic reconstruction.

Issuer identity context

bin, country, bank, and card_brand help Zahlen determine whether behavior belongs to an issuer cohort, a region, a brand, or an incomplete record.

Event timestamp

event_timestamp supports timeline ordering and historical comparison. Without timing context, the platform has less ability to distinguish old instability from current instability.

Recovery outcome fields

recovered, final_success, payment_status, and decision_state allow the recovery-rate calculation to determine whether the payment eventually succeeded.

Data completeness score

The validation layer computes a data-completeness score from key optional fields. This helps operators understand whether weak analysis is caused by poor source data rather than weak issuer signals.

Request source

The request_source value helps identify whether a row came from canonical upload, legacy compatibility, or another recognized source format. This improves debugging and operational interpretation.