What Zahlen is, the business problem it solves, and how the platform is organized
Audience
Merchants | Developers | Integration Engineers
Zahlen API User Guide v1.0
Source baseline: zahlen_deploy_0616A.tar.gz | June 2026
Chapter purpose |
This chapter gives readers the mental model they need before they create credentials or send their first API request. It explains Zahlen in plain language, shows the recurring-payment problem it addresses, and maps the commercial API to the wider platform architecture. |
Learning objectives |
By the end of this chapter, you should be able to explain what Zahlen does, describe why payment recovery requires evidence-driven decisions, identify the major platform layers, and trace a payment event through the end-to-end commercial workflow. |
What is Zahlen?
Zahlen is a recovery-intelligence platform for recurring and card-on-file payments. It helps a merchant decide whether a declined payment should be retried, when another authorization attempt should occur, and how the result should be recorded for future analysis.
The platform is not a payment processor and does not replace a merchant's billing system, gateway, acquirer, or issuer. Instead, Zahlen sits beside the payment stack as a decision and evidence layer. It accepts payment-event data, evaluates retry opportunities, returns explainable recommendations, records real-world outcomes, and transforms accumulated evidence into reporting and operational intelligence.
Concept | Meaning |
Payment evidence | Facts supplied by the merchant or produced by the payment stack, such as a decline code, issuer BIN, amount, attempt number, processor, timestamp, and merchant reference. |
Retry decision | An explicit recommendation describing whether a retry is appropriate and, when available, the recommended retry day, confidence, and reasons. |
Retry outcome | The observed result of an attempted retry, including approval or final decline evidence and the identifiers that connect the outcome to the original decision. |
Recovery intelligence | Patterns derived from completed evidence, including decline explanations, recovery performance, issuer behavior, and operational recommendations. |
Investigation and reporting | Durable, tenant-scoped records that help merchants and operators understand larger trends, exceptions, and system performance. |
A simple way to think about Zahlen |
Your payment system tells Zahlen what happened. Zahlen recommends what to do next. Your payment system performs the attempt. Then it tells Zahlen what actually happened. |
Who uses Zahlen?
Merchants use Zahlen to improve the recovery of recurring revenue while reducing unnecessary authorization attempts.
Developers integrate payment-event, retry-decision, outcome, and webhook endpoints into billing and payment services.
Integration engineers connect Zahlen to gateways, processors, data pipelines, observability systems, and enterprise controls.
Operators and analysts use the administrative platform to investigate issuer behavior, monitor classifications, manage watchlists, review recommendations, and supervise investigation runs.
This guide concentrates on the first three audiences. Administrative capabilities are introduced only when they affect the commercial integration or the identifiers developers must preserve.
The business problem Zahlen solves
Recurring-payment recovery looks simple from a distance: a payment fails, so the merchant tries again. In practice, a decline is evidence of a condition - not a complete explanation of that condition. The same visible decline code can have different operational meanings depending on the issuer, card brand, country, amount, processor, attempt number, billing-cycle position, and recent recovery history.
The fixed retry schedule is the answer
Immediate retries may repeat the same failure condition before it has had time to change.
Too many attempts can increase processor costs, create unnecessary issuer traffic, or harm the customer experience.
Waiting too long can reduce the chance of recovery and delay merchant revenue.
A single global schedule ignores issuer-level and decline-category differences.
A recommendation without outcome reporting cannot be measured or improved.
The four operational questions
Concept | Meaning |
Should this payment be retried? | Some declines are recoverable, some require customer action, and some should not be repeatedly attempted. |
When should the retry occur? | The timing of another attempt can materially affect authorization success. |
Why was this recommendation produced? | Developers and operators need reason codes, confidence, policy context, and traceable identifiers. |
Did the recommendation work? | The retry outcome must be reported so recovery performance can be measured against the original decision. |
The core business value |
Zahlen replaces an undifferentiated "retry everything" approach with a tenant-safe, evidence-driven workflow that separates recommendation from execution and connects every recommendation to an observed outcome. |
Example scenario
A subscription charge for $29.99 is declined with code 51 on the customer's first attempt. The merchant sends the payment event to Zahlen with a stable event ID, amount in minor units, issuer BIN, card brand, processor, and attempt number. Zahlen returns a decision with a recommendation, confidence, reason detail, and durable identifiers. The merchant follows the approved retry schedule, submits the next authorization through its processor, and reports the result to Zahlen.
That completed chain becomes evidence for future decisions and reporting.
1 Decline observed Merchant payment stack records the event. | 2 Evidence sent Client posts the payment event to Zahlen. | 3 Decision returned Zahlen provides recommendation and reasons. | 4 Retry executed Merchant submits the authorized retry. | 5 Outcome reported Observed result closes the learning loop. |
The commercial workflow
The developer experience is organized around a five-stage flow. Each stage produces or consumes identifiers that should be stored in application logs and durable business records.
1 Payment Event Submit one or more payment-event records. | 2 Retry Decision Read a generated decision or request one directly. | 3 Retry Outcome Report the real processor or settlement result. | 4 Investigation Run Connect ingestion to durable analysis. | 5 Reporting Review recovery, usage, and operational trends. |
Stage 1 - Payment Event
The payment event is the evidence record. A merchant supplies a stable `event_id` and any available context such as decline code, response code, issuer BIN, amount, currency, attempt number, timestamps, payment token, subscription ID, processor, and metadata. The public request deliberately excludes `tenant_id`; ownership is resolved from the authenticated API key.
Stage 2 - Retry Decision
A decision tells the client what Zahlen recommends. Depending on the selected contract, the response can include the decision value, recommended retry day, confidence, confidence score, reason codes, reason detail, policy source, matched policy ID, request ID, and decision ID. Recommendation is not execution: the merchant remains responsible for submitting the payment attempt through its payment stack.
Stage 3 - Retry Outcome
After the merchant performs the attempt, the outcome endpoint records what actually happened. Reporting an outcome connects the recommendation to observed evidence, such as an approval, final decline, approval code, settled amount, currency, and outcome timestamp.
Stage 4 - Investigation Run
Payment-event ingestion can produce an upload job and an investigation run. These durable resources bridge raw evidence into Recovery Intelligence, issuer monitoring, classifications, and reports. Administrative authorization is separate from ordinary merchant API-key access.
Stage 5 - Reporting
Reporting turns individual events and outcomes into trends: event volume, accepted and rejected records, retry candidates, confidence distributions, decision distributions, processor results, recovery performance, usage, and operational health.
Traceability rule |
Preserve `event_id`, `payment_event_batch_id` or `batch_id`, `upload_job_id`, `request_id`, and `decision_id` whenever they are returned. These identifiers connect the client request, Zahlen decision, downstream processor result, support investigation, and audit evidence. |
Platform architecture
Zahlen is organized into layers. The layers separate the public developer contract from merchant administration, operator workflows, durable storage, and governance. This separation lets developers integrate a focused commercial API without depending on internal operator routes.
Layer | Contains | Primary responsibility |
Merchant systems | Billing services, subscription platforms, payment orchestrators, gateways, processors, data pipelines, and monitoring tools. | Create evidence, execute payment attempts, and consume responses. |
Commercial API | `/v1/payment-events`, retry-decision routes, retry outcomes, webhook subscriptions, health, version, and discovery. | Authenticate merchant requests, validate schemas, return durable identifiers, and enforce commercial controls. |
Layer | Contains | Primary responsibility |
Decision and ingestion services | Payment-event normalization, policy evaluation, idempotency, batch processing, processor-result correlation, and outcome recording. | Convert evidence into recommendations and durable processing state. |
Recovery Intelligence | Recovery Truth, decline explanations, retry analysis, issuer behavior, health snapshots, radar signals, and classifications. | Transform completed evidence into explainable operational intelligence. |
Administrative control plane | Operator HTML, administrative JSON APIs, investigation runs, watchlists, recommendations, incidents, queues, and supervisor dashboards. | Support human investigation, governance, and enterprise operations. |
Governance and persistence | Tenant-scoped repositories, API keys, usage plans, quotas, audit trail, activity, certification, and durable databases. | Protect ownership, preserve history, and provide evidence for safe operation. |
Architecture flow
1 Merchant client Sends authenticated JSON over HTTPS. | 2 API gateway layer Authenticates, validates, limits, and audits. | 3 Core services Ingest, normalize, decide, and persist. | 4 Intelligence layer Builds recovery and issuer evidence. | 5 Portal and reports Expose tenant-scoped results and controls. |
Public, administrative, and internal surfaces
Concept | Meaning |
Merchant API - `/v1/*` | Used by merchant applications. Merchant-facing calls authenticate with `X-API-Key` unless a route is explicitly public, such as a deployment health check. |
Operator HTML - `/admin/*` | Used by authenticated human operators. These pages normally rely on a login session, not a merchant API key. |
Administrative JSON - `/v1/admin/*` | Used for governed automation, reporting, supervision, and enterprise administration. Access is separately authorized. |
Background services | Workers, supervisors, repositories, and scheduled evaluation processes. These are deployment components rather than public client contracts. |
Integration boundary |
A merchant integration should depend only on documented public contracts. Do not call internal services or infer administrative access from the existence of a `/v1/admin/*` route. |
Tenant-safe architecture
Tenant isolation is a foundational design rule, not an optional filter. The authenticated API key resolves the merchant, tenant, and actor context. Public request bodies do not control ownership. A caller therefore cannot select another tenant simply by changing JSON, a form field, or a query parameter.
Ownership model
Concept | Meaning |
`tenant_id` | The ownership boundary. It determines which records, keys, quotas, audit entries, events, decisions, outcomes, and administrative resources belong together. |
`merchant_id` | Business context within the tenant. It is useful for reporting and integration, but it is not a substitute for the authenticated ownership boundary. |
`X-API-Key` | The merchant credential used to resolve authorized context for merchant-facing API calls. |
Session authentication | The usual authorization mechanism for human-facing administrative HTML pages. |
Why this matters to developers
Do not include a tenant ID in a public request unless the documented schema explicitly defines one for a non-ownership purpose.
Treat a cross-tenant 404 or empty result as an isolation outcome, not evidence that a filter should be bypassed.
Keep development, staging, and production keys, base URLs, and databases separate.
Log durable resource identifiers, but never log the complete API key.
Expect permission checks to fail closed when tenant context is missing or invalid.
Security principle |
Authentication establishes who is calling. Tenant resolution establishes what that caller owns. Authorization establishes which operation the caller may perform. All three checks are required. |
What Zahlen does not do
Zahlen does not directly move money or replace your payment processor.
Zahlen does not guarantee that a recommended retry will be approved.
Zahlen does not make optional evidence appear when the merchant has not supplied or generated it.
Zahlen does not remove the merchant's responsibility for payment security, privacy, card-network rules, processor contracts, or regulatory compliance.
Zahlen does not treat a recommendation as an observed result; the outcome must be reported separately.
Chapter summary
Zahlen is an evidence and decision layer for recurring-payment recovery.
The platform helps answer whether to retry, when to retry, why the decision was made, and whether it worked.
The commercial workflow is Payment Event -> Retry Decision -> Retry Outcome -> Investigation Run -> Reporting.
The public API is separated from administrative and internal services.
Tenant ownership comes from authenticated context, not merchant-supplied ownership fields.
Durable identifiers provide traceability across ingestion, decisions, outcomes, investigations, and audit records.
Next chapter |
Chapter 2 - Getting Started explains how to prepare an account, obtain an API key, select an environment and usage plan, and complete the first authenticated request. |