ZAHLEN

API User Guide

Chapter 12 - Audit & Compliance

Audit trail | Tenant isolation | Governance controls

Version 1.0 | Source baseline: zahlen_deploy_0616A.tar.gz | June 2026 Commercial developer experience | Tenant-safe operations | Explainable retry intelligence

‌Chapter 12 - Audit & Compliance

Audit and compliance are not separate from API design. They are built into how requests are authenticated, how ownership is resolved, how actions are recorded, and how operators verify that controls continue to work. For merchants and integration teams, these capabilities make it possible to answer practical questions such as: Who called the API? Which key was used? Which tenant owned the resource? What decision was returned? Was a quota enforced? What changed after an administrative action?

Zahlen provides the technical evidence needed for operational review and governance. It does not replace a merchant's own legal, privacy, security, or payment-compliance obligations. Each customer remains responsible for deciding what data may be transmitted, how long local records are retained, and which staff may access them.

1. ‌Why auditability matters

   • Incident response: correlate a reported problem with a request, API key, endpoint, decision, outcome, batch, or investigation run.

   • Security review: identify unusual key activity, failed authentication, access denials, and post-revocation attempts.

   • Operational accountability: show who changed plans, quotas, policies, keys, or workflow state and when the change occurred.

   • Customer support: trace a merchant event through ingestion, decisioning, retry outcome, investigation, and reporting.

   • Governance certification: prove that tenant isolation, rate limits, quotas, audit logging, and portal controls are active and tested.

     
     

     Question	Evidence commonly used
     Who made the call?	Actor identity, API key ID or safe fingerprint, authenticated user or service identity
     What operation ran?	HTTP method, endpoint, action name, resource type, request ID
     Which tenant owned it?	Resolved tenant_id and merchant context from

     
     

     Question	Evidence commonly used
     	authentication
     What happened?	Status code, result, decision ID, outcome ID, before-and-after state
     When did it happen?	Server timestamp, created_at, updated_at, processing and completion times
     How long did it take?	Latency, queue timing, background-job timing, downstream status

     
     

2. ‌Audit trail

   The Zahlen commercial governance layer can record API activity and privileged administrative actions as durable audit evidence. A useful audit record connects the authenticated caller to the operation and its result without storing the full secret API key or unnecessary payment data.

   
   

   Audit element	Purpose	Client responsibility
   request_id	Correlates one API exchange across services and support	Capture it in logs and support tickets
   api_key_id / fingerprint	Identifies the credential without exposing the secret	Never log the full X-API-Key value
   tenant_id	Confirms ownership scope	Do not supply or override it from merchant JSON
   endpoint and method	Shows what operation was attempted	Log route and HTTP method
   status_code	Separates success, validation, authorization, throttling, and server failure	Classify before retrying
   latency	Supports runtime and performance analysis	Monitor percentiles and sustained change
   resource identifiers	Connects event, batch, decision, outcome, and run records	Persist durable IDs returned by Zahlen
   before/after state	Explains privileged changes	Record administrative changes through approved routes

   
   

3. ‌Correlation identifiers

   A complete audit story depends on preserving the identifier chain created across the commercial workflow.

   
   

   Identifier	Created by	Use in audit and support
   event_id	Merchant	Stable correlation for one payment event
   payment_event_batch_id / batch_id	Zahlen	Groups one ingestion request
   upload_job_id	Zahlen	Links ingestion to background processing and investigation runs
   request_id	Zahlen	Correlates an API request and support investigation
   decision_id	Zahlen	Identifies the retry decision that controlled merchant behavior
   outcome_id	Zahlen	Identifies the recorded real-world result
   subscription_id	Zahlen	Identifies a webhook subscription
   investigation run ID	Zahlen	Links completed evidence to downstream analysis

   
   

   {

   "event_id": "evt_20260616_0001", "request_id": "req_example_001", "decision_id": "dec_example_001", "outcome_id": "out_example_001", "upload_job_id": "job_example_001"

   }

1. ‌Tenant isolation

   Tenant isolation prevents one customer from reading, changing, or inferring another customer's data. Zahlen derives tenant ownership from the authenticated API key for merchant routes and from authenticated session or administrative context for operator routes. Repository queries and service calls must continue carrying that tenant context all the way to persistence and rendering.

   
   

   Layer	Tenant-isolation expectation
   Request authentication	Resolve the tenant from X-API-Key or approved administrative identity
   Request model	Do not expose tenant_id as a merchant-controlled ownership selector

   
   

   Layer	Tenant-isolation expectation
   Service layer	Pass tenant context explicitly to downstream services
   Repository layer	Filter reads and writes by tenant_id plus the resource identifier
   HTML and JSON rendering	Return only records visible to the authenticated tenant
   Exports and reports	Preserve the same tenant filters used by interactive views
   Background workers	Load tenant scope from durable job ownership, not a global default
   Errors	Fail closed when tenant context is missing, unresolved, or inconsistent

   
   

2. ‌Understanding tenant-safe 404 responses

   A resource owned by another tenant should normally appear unavailable. Returning 404 instead of revealing that the resource exists reduces cross-tenant information leakage. A client must not interpret every 404 as proof that an identifier was never created; it can also mean that the authenticated tenant is not allowed to see it.

   1. Confirm that the client is using the expected environment and hostname.

   2. Confirm that the correct API key is loaded.

   3. Confirm the event, batch, decision, outcome, or run identifier.

   4. Check whether the resource was created under another merchant account or environment.

   5. Use request IDs and audit records for support; do not weaken repository filters to make the record visible.

3. ‌Governance controls

   Governance controls turn security and operational expectations into enforceable, reviewable behavior. They cover the entire commercial API lifecycle rather than only authentication.

   
   

   Control family	What it protects	Evidence to review
   API key management	Credential creation, hashing, rotation, and revocation	Key lifecycle records, audit events, revoked-key tests
   Usage plans	Contracted capabilities and service levels	Plan assignment, capability checks, negative tests
   Rate limits and quotas	Runtime capacity and contracted usage	Enforcement records, 429 behavior, quota checks
   Audit trail	Traceability and accountability	Request correlation, status, latency, actor, tenant
   Tenant isolation	Customer ownership boundary	Cross-tenant tests, repository filters, fail-closed behavior

   
   

   Control family	What it protects	Evidence to review
   Developer portal controls	Authorized visibility and self-service actions	Role checks, tenant-scoped pages and APIs
   Runtime health	Continued operation of workers and services	Health status, queue state, last cycle, failures
   Governance certification	Evidence that required controls are present and tested	Certification results, runbooks, restart durability

   
   

4. ‌Governance certification

   Governance certification is an evidence-based review of whether the commercial API is safe to operate. It is not a marketing label and it should not be treated as permanent. Certification must be repeated after material changes to authentication, tenant ownership, persistence, quotas, portal authorization, or deployment topology.

   1. Confirm that every merchant route derives ownership from the authenticated key.

   2. Run negative cross-tenant tests for reads, writes, exports, and administrative actions.

   3. Verify key generation, secure hashing, rotation overlap, revocation, and post-revocation denial.

   4. Verify plan restrictions, rate-limit enforcement, quota exhaustion, and HTTP 429 behavior.

   5. Confirm that audit records contain sufficient correlation without exposing credentials or prohibited data.

   6. Verify restart durability for jobs, outcomes, monitoring state, and governance records.

   7. Confirm that missing tenant context fails closed and never falls back to a default production tenant.

   
   

   Fail closed

   A missing tenant context, unresolved key, or failed ownership check must deny access. Production code must not fall back to a development tenant, global tenant, or first available record.

   
   

5. ‌Data minimization and payment data

   Auditability does not require copying every request field into logs. Zahlen request models include payment tokens, merchant references, issuer evidence, and optional metadata. These fields should be used carefully. A generic metadata object is not permission to store prohibited cardholder data.

   
   

   Prefer	Avoid
   Merchant-generated payment tokens	Full primary account numbers
   Stable customer, subscription, order, and invoice references	CVV or security codes
   Issuer BIN and normalized decline evidence when contractually approved	Passwords, authentication secrets, or raw bank credentials
   Minor-unit monetary values and currency	Unstructured dumps of processor payloads containing sensitive data

   
   

   Prefer	Avoid
   Safe API key IDs or fingerprints	Complete X-API-Key values
   Request and resource identifiers	Screenshots as the only evidence

   
   

6. ‌Merchant and integration-team responsibilities

   • Classify the data your application sends and confirm that it is allowed by contract and policy.

   • Restrict production API keys to server-side applications and approved operators.

   • Maintain local logs that can correlate with Zahlen request IDs without storing secrets.

   • Define retention and deletion policies for local payment-event, decision, and outcome records.

   • Monitor authentication failures, 403/404 anomalies, 409 conflicts, 429 enforcement, and sustained 5xx responses.

   • Rotate keys through a controlled overlap procedure and preserve evidence of the change.

   • Report observed retry outcomes accurately so governance and performance reporting are based on real evidence.

   • Ensure HTTP or webhook retries never create payment attempts outside Zahlen's fixed Day 1, Day 2, Day 6, and Day 16 schedule.

7. ‌Practical audit logging example

   The following Python example logs safe correlation data while excluding the API key and request body. Production applications should use structured logging and a centralized log platform.

   import logging

   import os import requests

   log = logging.getLogger("zahlen.client") base_url = os.environ["ZAHLEN_BASE_URL"] headers = {

   "X-API-Key": os.environ["ZAHLEN_API_KEY"], "Content-Type": "application/json", "Idempotency-Key": "order-8842-attempt-2",

   }

   response = requests.post( f"{base_url}/v1/_next/retry-decision", headers=headers,

   json={"attempt_number": 2, "decline_code": "51"}, timeout=20,

   )

   request_id = response.headers.get("X-Request-ID") body = response.json() if response.content else {} log.info(

   "zahlen_api_call", extra={

   "method": "POST",

   "path": "/v1/_next/retry-decision", "status": response.status_code,

   "request_id": request_id or body.get("request_id"), "decision_id": body.get("decision_id"), "idempotency_key": "order-8842-attempt-2",

   },

1. ‌Audit and compliance review checklist

   
   

   Review area	Ready when
   Authentication	All merchant calls use X-API-Key over HTTPS; secrets are not logged
   Ownership	tenant_id comes only from authenticated context
   Correlation	Request, event, batch, decision, outcome, and job IDs are retained
   Validation	Unknown fields and invalid values are rejected and monitored
   Key lifecycle	Creation, rotation, revocation, and unusual use are auditable
   Quotas	Plan, usage, quota checks, and 429 activity are reviewed together
   Tenant tests	Cross-tenant reads, writes, exports, and actions fail
   Sensitive data	Logs and metadata exclude prohibited cardholder and credential data
   Runtime	Audit persistence and governance controls survive service restart
   Change management	Material control changes trigger contract and governance tests

   
   

2. ‌Summary

Zahlen audit and compliance controls make the commercial workflow traceable without weakening tenant isolation. The audit trail records who did what, when, through which credential and endpoint, and with what result. Tenant ownership is derived from authenticated context and preserved through services, repositories, pages, APIs, exports, and background work. Governance controls verify that keys, plans, quotas, audit logging, portal authorization, and fail-closed behavior continue to operate as designed.

For integration teams, the practical rule is straightforward: preserve safe identifiers, protect secrets, minimize sensitive data, treat tenant boundaries as absolute, and use approved API operations so that every important action remains explainable and auditable.

‌Source note