Phase 6 — API & Integration Documentation

This chapter explains how API ingestion should be understood in Zahlen as a replay-safe, event-oriented integration path for submitting payment events, issuer signals, recovery outcomes, and operational evidence.

Chapter Purpose

API ingestion is the integration path used when a merchant, processor, billing system, or internal data pipeline sends payment events directly into Zahlen through a structured service interface instead of uploading a CSV file.

This chapter explains the purpose of API ingestion, the expected event model, canonical field conventions, validation expectations, idempotency, replay-safe ingestion, operational error handling, and troubleshooting patterns.

The goal of API ingestion is not merely to accept data. The goal is to receive operational evidence in a form that can support issuer cognition, recovery observability, replay verification, governance confidence, incident routing, and network-safe aggregation.

Operator Perspective API ingestion allows Zahlen to move from file-based analysis into live operational intelligence. Each submitted event should help the platform understand issuer behavior, recovery timing, response-code meaning, and whether the event can be safely replayed later.

 

What is API Ingestion?

API ingestion is the process of accepting structured payment and issuer-behavior events through a programmatic interface.

An API is an application programming interface. It allows external or internal systems to submit data to Zahlen in a consistent format. In the context of Zahlen, API ingestion is used to send payment events, retry outcomes, issuer-health signals, telemetry evidence, and other operational records into the platform.

API ingestion differs from CSV ingestion in timing and operational posture. CSV ingestion is typically batch-oriented. A user uploads a file, runs an analysis, and reviews the resulting artifacts. API ingestion is event-oriented. It is designed to support more frequent, automated, and eventually near-real-time submission of evidence.

This difference matters because live operational intelligence depends on event continuity. When events arrive through an API, Zahlen can update issuer health, alerts, investigations, action queues, system health, and network intelligence with less manual delay.

Ingestion Path	Definition	Operational Use
CSV ingestion	A file-based ingestion path where operators upload transaction or retry data.	Best for first analysis, historical review, offline diagnostics, and operator onboarding.
API ingestion	A service-based ingestion path where systems submit structured events directly.	Best for recurring integration, operational monitoring, and live issuer intelligence.
Kafka or streaming ingestion	A continuous event-stream path where events are published through a durable stream.	Best for high-volume, distributed, production-grade event infrastructure.

 

Why API Ingestion Matters

API ingestion matters because Zahlen’s long-term value depends on observing payment behavior as an operational system rather than as occasional historical reports.

A subscription business may process thousands or millions of payment events across countries, issuers, card brands, retry windows, and customer cohorts. If those events reach Zahlen only through occasional uploads, the platform can analyze history but cannot provide continuous operational visibility.

API ingestion allows payment evidence to flow into Zahlen more regularly. That evidence can then support issuer-health snapshots, alert generation, recovery trend analysis, incident coordination, supervisor visibility, replay verification, and governance review.

In practical terms, API ingestion is the bridge between first-hour diagnostics and production operational intelligence.

Strategic Interpretation CSV ingestion helps teams begin using Zahlen. API ingestion helps Zahlen become part of the operating system of payment intelligence.

 

Canonical API Event Model

The canonical API event model is the preferred structure for events submitted into Zahlen.

A canonical event is a normalized representation of payment behavior that can be understood consistently across processors, merchants, billing systems, and internal data pipelines. It allows Zahlen to reason about events using stable platform concepts rather than processor-specific terminology.

The event model should preserve the original source evidence while also mapping important values into canonical fields. This means a source system can send its native processor code, but Zahlen should still receive or derive a canonical response_code field for downstream analysis.

Canonical Field	Definition	Why It Matters
event_id	A unique identifier for the submitted event.	Supports idempotency, duplicate prevention, and replay-safe lineage.
event_type	The type of event, such as authorization_attempt, retry_attempt, settlement_result, issuer_signal, or recovery_outcome.	Allows Zahlen to route the event to the correct interpretation path.
event_at	The timestamp when the event occurred in the source system.	Supports ordering, timeline reconstruction, and replay analysis.
received_at	The timestamp when Zahlen received the event.	Helps distinguish source event time from platform ingestion time.
merchant_id	The tenant or merchant context associated with the event.	Supports tenant isolation and merchant-specific investigation.
issuer_bin	The issuer identification prefix or issuer cohort key.	Supports issuer-level analysis and issuer cognition.
issuer_country	The issuing country or regional context.	Supports cross-country degradation and regional analysis.
card_brand	The payment network brand associated with the event.	Supports brand-level comparison and network behavior interpretation.
response_code	The canonical authorization, decline, or processor response code.	Supports decline analysis, recovery interpretation, and issuer behavior modeling.
retry_day	The relative day in the deterministic retry lifecycle.	Supports recovery curve analysis and fixed cohort interpretation.
recovered	A normalized indicator showing whether payment recovery occurred.	Supports recovery-rate and marginal recovery analysis.
source_system	The system that produced or forwarded the event.	Supports lineage, troubleshooting, and trust-domain interpretation.

 

Event Types

An event type describes what kind of operational evidence is being submitted.

Event typing matters because not every event should be interpreted the same way. An authorization attempt records a payment decision. A retry attempt records a lifecycle recovery observation. A settlement result records downstream money movement. An issuer signal may summarize derived issuer behavior. A recovery outcome may confirm that a previously failed payment has recovered.

Event Type	Definition	Operator Meaning
authorization_attempt	A payment authorization request and its result.	Shows how the issuer responded at a specific point in time.
retry_attempt	A retry event within the deterministic recovery lifecycle.	Supports Day 1, Day 2, Day 6, and Day 16 recovery interpretation.
settlement_result	A downstream settlement status after authorization.	Helps distinguish authorization approval from completed settlement.
recovery_outcome	An event confirming whether a payment eventually recovered.	Supports recovery curves, cohort recovery, and marginal recovery calculation.
issuer_signal	A derived signal describing issuer behavior or health.	Supports monitoring, alerts, incidents, and network intelligence.
telemetry_event	An event describing processing, enrichment, or evidence-quality behavior inside the system.	Helps operators understand whether ingestion and enrichment ran correctly.

 

Idempotency and Duplicate Protection

Idempotency is the property that submitting the same event more than once should not create duplicate operational meaning.

API ingestion must assume that retries, network failures, client timeouts, and integration errors may cause the same event to be sent more than once. If Zahlen treats every duplicate submission as a new event, issuer-health metrics, alert counts, recovery rates, and telemetry signals may become distorted.

The event_id field is the primary mechanism for idempotency. A source system should provide a stable event identifier. If the same event_id is submitted again with the same content, Zahlen should recognize it as a duplicate or replay-safe resubmission. If the same event_id is submitted with conflicting content, Zahlen should treat that as a validation or lineage issue.

Why This Matters Duplicate protection is essential for issuer intelligence. A repeated event should not make an issuer look more degraded, more volatile, or more active than it actually was.

 

Idempotency Scenario	Meaning	Recommended Handling
Same event_id, same payload	The source resent an identical event.	Treat as a duplicate or idempotent success.
Same event_id, different payload	The source submitted conflicting evidence for the same event.	Flag for validation review or conflict handling.
No event_id	The source did not provide a stable event identity.	Accept only if a deterministic surrogate key can be safely generated.
Multiple event_ids for one source event	The source may be generating unstable identifiers.	Review integration design before trusting metrics.

 

Replay-Safe API Ingestion

Replay-safe API ingestion means that submitted events are stored, ordered, and interpreted in a way that allows historical conclusions to be reconstructed later.

Replay safety requires more than accepting event payloads. Zahlen must preserve event identity, event timing, source system context, canonical mappings, original source values, transformation decisions, validation results, and downstream lineage.

Lineage is the traceable path from source event to derived conclusion. In API ingestion, lineage may include the received payload, canonical normalization, issuer-health event generation, alert creation, incident routing, action-queue creation, and supervisor dashboard presentation.

Replay-safe ingestion supports governance because operators and auditors may need to understand why a signal was produced. If a signal cannot be traced back to the events that created it, the conclusion is weaker.

Replay-Safe Requirement	Definition	Why It Matters
Stable event identity	Every event has a unique and durable identity.	Supports replay, duplicate control, and event lineage.
Source timestamp preservation	The event retains the source system occurrence time.	Supports deterministic ordering and timeline reconstruction.
Canonical normalization record	The platform records how source fields mapped into canonical fields.	Supports auditability and schema governance.
Original source preservation	Important source values are retained without destructive alteration.	Allows troubleshooting and source evidence review.
Validation state	The platform records whether the event passed validation, generated warnings, or was rejected.	Supports operational confidence and governance review.
Downstream linkage	Derived alerts, signals, incidents, and tasks can be traced back to source events.	Supports investigation and supervisor accountability.

 

Validation Expectations

API validation is the process of determining whether a submitted event is complete, interpretable, and safe to use in downstream analysis.

Validation should be strict enough to protect operational intelligence but flexible enough to support real integration realities. Some fields may be required for all events. Other fields may be required only for certain event types.

For example, an authorization_attempt should usually include response_code, issuer context, event_at, and authorization status. A telemetry_event may not require issuer_bin if it describes platform processing rather than a payment outcome. A recovery_outcome should include enough linkage to connect the recovery to the failed payment or cohort.

Validation Category	Definition	Operational Meaning
Required field validation	Checks whether mandatory fields are present.	Prevents incomplete events from entering critical workflows.
Type validation	Checks whether values use expected formats, such as timestamps or booleans.	Prevents malformed values from corrupting analysis.
Canonical mapping validation	Checks whether source values can be mapped into platform concepts.	Protects downstream services from ambiguous fields.
Tenant validation	Checks whether the event belongs to an authorized tenant or merchant context.	Supports isolation and access control.
Replay validation	Checks whether the event contains enough identity and context for replay.	Protects governance integrity and auditability.
Semantic validation	Checks whether the event makes operational sense.	Detects contradictory or suspicious payloads.

 

Accepted, Rejected, and Quarantined Events

API ingestion should distinguish between accepted, rejected, and quarantined events.

An accepted event is usable for downstream analysis. A rejected event cannot be processed because it fails required validation. A quarantined event is preserved for review but not allowed to influence normal operational intelligence until the issue is resolved.

Quarantine is useful when the platform receives potentially important evidence that is not currently safe to trust. For example, an event may have a valid response_code and issuer_bin but an inconsistent timestamp, conflicting idempotency key, or missing tenant context. In such cases, preserving the event may be valuable, but allowing it to influence alerts immediately may be unsafe.

Ingestion State	Definition	Recommended Operator Interpretation
Accepted	The event passed validation and can enter downstream workflows.	The event may contribute to issuer health, alerts, recovery analysis, and investigations.
Rejected	The event failed required validation and was not ingested for analysis.	The integration owner should correct and resubmit if appropriate.
Quarantined	The event was preserved but isolated from normal intelligence workflows.	Review is required before the event can influence governance or operational conclusions.
Duplicate	The event was already submitted or is idempotently equivalent to a prior event.	Do not count the event twice.
Conflict	The event identity conflicts with a different payload or interpretation.	Escalate for integration and lineage review.

 

Canonical Response Code Handling

API ingestion should follow the same response_code convention used throughout Zahlen.

The canonical response_code field is the primary platform-level field for authorization, decline, and processor response interpretation. Source systems may send processor-specific fields such as decline_code, processor_code, payment_response_code, or legacy aliases, but the API ingestion process should map those values into response_code whenever possible.

Response codes should be treated as strings. This prevents accidental loss of leading zeros and preserves alphanumeric processor values. The original source value should be preserved when possible so that operators can trace canonical interpretation back to source evidence.

Important Convention The canonical field name is response_code. API integrations should not make processor-specific terms the primary platform concept, even when compatibility aliases are accepted.

 

Tenant Isolation and API Ingestion

Tenant isolation is the rule that raw merchant-level data, customer-level data, payment-level data, and merchant-identifiable operational details must remain within the correct tenant boundary.

API ingestion must enforce tenant isolation because live event submission can become a high-volume source of sensitive operational data. Each event should be associated with an authorized tenant or merchant context before it contributes to downstream intelligence.

Tenant isolation also supports future public-safe aggregation. Local tenant events may eventually contribute to anonymized, aggregated issuer signals only after raw data is transformed into safe cohort-level intelligence and minimum crowd thresholds are satisfied.

The API ingestion layer should therefore be designed as a trust boundary. It receives data, validates identity, maps fields, records lineage, and prevents unsafe cross-tenant interpretation.

Authentication and Authorization

Authentication verifies the identity of the system submitting API events. Authorization determines what that system is allowed to submit, access, or modify.

For production-grade API ingestion, each submitting system should use a secure credential or token associated with a defined tenant, environment, or integration role. The platform should not trust an event merely because it is well-formed. It must also verify that the submitting party is permitted to send that event.

Role-based access control is the practice of limiting access based on assigned roles. In API ingestion, this may determine whether a client can submit production events, replay events, test events, telemetry events, or administrative corrections.

Security Interpretation API ingestion is a data boundary. Strong authentication, authorization, and tenant context controls are necessary before submitted events become operational evidence.

 

API Ingestion and System Health

API ingestion should contribute to system health visibility because operators need to know whether live event flow is healthy.

System health indicators may include event counts, accepted counts, rejected counts, quarantine counts, duplicate counts, latest received timestamp, processing lag, event durability, watermark advancement, and downstream platform event creation.

Watermark advancement is the process of recording how far the ingestion or processing pipeline has advanced through an event stream or event sequence. It helps operators determine whether the platform is keeping up with incoming data.

Processing lag is the delay between event occurrence, event receipt, and downstream interpretation. High lag may indicate ingestion pressure, processing failures, or downstream service issues.

Health Signal	Definition	Operator Interpretation
Accepted event count	Number of events successfully admitted into ingestion.	Shows whether valid data is flowing.
Rejected event count	Number of events rejected by validation.	May indicate integration errors or schema drift.
Quarantine count	Number of events isolated for review.	May indicate trust, lineage, or policy concerns.
Duplicate count	Number of repeated events detected.	May indicate retry behavior or unstable client submissions.
Latest received timestamp	Most recent event receipt time.	Shows whether live ingestion is current.
Watermark advancement	Progress marker through event processing.	Shows whether downstream processing is advancing.
Processing lag	Delay between source event time and platform processing.	May indicate operational pressure or failure.

 

Error Handling and Troubleshooting

API ingestion troubleshooting is the process of resolving integration, validation, identity, schema, and downstream processing issues.

Operators and integration teams should interpret ingestion errors as evidence-quality controls rather than mere technical failures. An event rejected for missing issuer_bin may be technically simple to fix, but operationally it means the event could not support issuer cognition. An event quarantined for conflicting event_id may indicate a deeper lineage risk.

Symptom	Likely Cause	Recommended Fix
Events are rejected for missing fields	Required canonical fields are absent.	Add required fields or configure source-to-canonical mapping.
Events are accepted but no issuer signals appear	Issuer identity or response_code is missing or not mapped.	Confirm issuer_bin, issuer_country, card_brand, and response_code mapping.
Duplicate events appear frequently	Client retries may be using unstable event identifiers.	Use stable event_id values and idempotency keys.
Events are quarantined	The event is potentially useful but not safe for downstream use.	Review validation warnings, tenant context, lineage, and timestamp consistency.
Processing lag increases	Ingestion volume or downstream processing may be under pressure.	Review system health, worker status, and queue depth.
Replay validation fails	Historical event reconstruction does not match expected output.	Review event ordering, canonical mapping, and lineage preservation.

 

API Ingestion vs Streaming Ingestion

API ingestion and streaming ingestion are related but not identical.

API ingestion usually involves direct event submission through service endpoints. Streaming ingestion uses a durable event stream, such as Kafka or another event bus, to publish and consume events at scale. API ingestion can be simpler to adopt. Streaming ingestion is better suited for high-volume distributed systems that require durable ordering, replay offsets, consumer groups, and event-bus survivability.

Zahlen’s long-term architecture includes CSV upload, API access, and Kafka streaming as three ingestion channels. API ingestion occupies the middle position: more automated and operational than CSV, but not necessarily as infrastructure-heavy as full streaming.

Architecture Interpretation CSV is the easiest way to begin. API ingestion is the practical production integration path. Streaming ingestion is the long-term high-volume event infrastructure path.

 

Recommended API Ingestion Workflow

A recommended API ingestion workflow begins with schema alignment. The integration team should map source fields into canonical Zahlen fields before sending production events.

Next, the team should test with a controlled event set. This allows validation rules, response_code mapping, issuer identity, retry lifecycle fields, and recovery outcomes to be confirmed before the integration sends high-volume production traffic.

After testing, the team should monitor ingestion health. The operator should review accepted events, rejected events, quarantine counts, latest received timestamps, event durability, downstream alerts, and replay validation behavior.

Finally, the team should periodically review schema drift. Schema drift occurs when a source system changes field names, field meanings, response-code formats, or event structure without updating the integration contract. Schema drift can weaken issuer intelligence and replay safety if it is not detected.

Workflow Step	Purpose	Evidence to Review
Map source schema	Align source fields to canonical Zahlen concepts.	Canonical field mapping, response_code mapping, issuer identity mapping.
Submit test events	Confirm validation and interpretation before production use.	Accepted events, rejected events, quarantine results, test findings.
Monitor health	Ensure live ingestion is operational.	Counts, lag, latest event time, watermark advancement, platform events.
Review downstream signals	Confirm events produce useful issuer intelligence.	Issuer health rows, alerts, investigations, action queue items.
Validate replay	Confirm historical event interpretation is reconstructable.	Replay consistency, lineage, validation logs, audit evidence.
Control schema drift	Detect source-side changes that affect meaning.	Validation warnings, missing fields, mapping changes, response-code changes.

 

Chapter Summary

API ingestion is the service-based integration path that allows Zahlen to receive structured payment and issuer-behavior events directly from operational systems.

A strong API ingestion design depends on canonical event fields, stable event identity, idempotency, tenant isolation, authentication, validation, replay-safe lineage, and system-health visibility.

API ingestion allows Zahlen to move beyond manual file analysis and toward live operational intelligence. It is the bridge between initial diagnostics and production-grade issuer cognition.

When implemented correctly, API ingestion turns payment events into durable evidence for recovery observability, issuer-health monitoring, incident coordination, governance confidence, replay verification, and eventually tenant-safe ecosystem intelligence.