Help and DocumentationContact Us

ZAHLEN

Chapter 4

Usage Plans

FREE, PROFESSIONAL, and ENTERPRISE

Audience

Merchants | Developers | Integration Engineers

Zahlen API User Guide v1.0

Source baseline: zahlen_deploy_0616A.tar.gz | June 2026

‌Chapter 4 - Usage Plans

A usage plan is the commercial policy assigned to a tenant. It can influence request quotas, short-window rate limits, enabled features, retention, support expectations, reporting, certification requirements, and developer-portal visibility. The plan belongs to the authenticated tenant context; it is not selected by sending a plan name in an API request.

1. ‌How plans fit the commercial workflow

   Workflow stage	Plan-controlled concern	Client responsibility
   Payment Event	Ingestion volume, batch policy, retention, reporting access	Submit valid tenant-owned evidence and store returned identifiers.
   Retry Decision	Decision request capacity, enabled contract, latency expectations	Use the approved decision contract and stable idempotency semantics.
   Retry Outcome	Outcome volume and retention	Report actual authorization or settlement evidence promptly.
   Investigation Run	Administrative visibility and processing scale	Track upload_job_id and use approved administrative access.
   Reporting	Dashboard, export, and commercial reporting access	Consume only capabilities explicitly enabled for the tenant.

   
   

   ‌Plan names do not replace capability checks

   Two tenants with the same plan name may have different contractual limits or optional features. A client must respond to explicit API behavior and capability metadata rather than assuming that every tenant has identical settings.

2. ‌Plan overview

   Plan	Typical fit	Primary goal	Integration guidance
   FREE	Evaluation, learning, proof of concept, and low-volume prototyping	Validate the workflow before production commitment	Build correct authentication, validation, 429 handling, and idempotency from the first prototype.
   PROFESSIONAL	Production merchant workloads with regular payment-event and decision traffic	Operate a dependable commercial integration	Monitor usage, batch responsibly, report outcomes, and establish production support procedures.
   ENTERPRISE	High-volume, multi-team, governed, or contract-specific deployments	Scale with formal controls and operational governance	Coordinate custom capacity, retention, access, reporting, certification, and support requirements.

   
   

   No unlimited plan

   A higher plan does not remove schema validation, tenant isolation, endpoint authorization, safe retry requirements, or operational safeguards. Every plan remains subject to technical and governance controls.

3. ‌FREE plan

   The FREE plan is intended for evaluation and low-volume prototyping. It lets a development team learn the API, validate payload mapping, test the end-to-end recovery workflow, and estimate future usage before moving production traffic.

   ‌Good uses for FREE

   • Build and test merchant-side request models.

   • Validate X-API-Key handling in a non-production environment.

   • Submit representative fictional or properly tokenized payment events.

   • Test the fixed Zahlen retry schedule of Day 1, Day 2, Day 6, and Day 16.

   • Practice outcome reporting and identifier correlation.

   • Implement 401, 403, 422, 429, and transient 5xx handling.

   • Run contract and smoke tests before production onboarding.

     
     

     ‌FREE integration expectations

     Expectation	Recommended approach
     Traffic	Use small, representative test datasets rather than production-scale loads.
     Quotas	Assume conservative limits and display quota exhaustion clearly to developers.
     Availability	Treat the environment as an evaluation surface unless a separate service commitment is documented.
     Data	Use fictional examples or approved tokenized test data.
     Migration	Keep configuration external so the same client can move to PROFESSIONAL without code changes.

     
     

     Prototype correctly

     Do not postpone error handling, idempotency, secret management, or tenant-safe identifiers because traffic is small. A prototype often becomes the foundation of the production integration.

4. ‌PROFESSIONAL plan

   The PROFESSIONAL plan is the normal fit for production merchant workloads. It supports sustained use of the commercial workflow while retaining clear tenant-scoped controls, usage monitoring, quotas, and operational accountability.

   ‌Production responsibilities

   • Use separate production keys and base URLs.

   • Monitor request volume, latency, authentication failures, 429 responses, and outcome-reporting lag.

   • Batch payment events only when batching improves reliability and does not delay time-sensitive processing.

   • Preserve event_id, batch_id, upload_job_id, request_id, and decision_id in application logs.

   • Implement bounded retries with exponential backoff and jitter.

   • Rotate credentials without downtime and review key activity after cutover.

   • Maintain support ownership for both merchant-side and Zahlen-side incidents.

     
     

     ‌Typical PROFESSIONAL operating pattern

     1 Ingest Send single events or controlled batches.

     2 Decide Request or retrieve retry decisions.

     3 Execute Apply the fixed Day 1, 2, 6, and 16 schedule as directed.

     4 Report Send actual retry outcomes.

     5 Monitor Review usage, errors, and unresolved processing.

     
     

     Operational area	What to monitor	Escalation signal
     Authentication	401 rate and revoked-key attempts	Sudden spike or use of a retired key.
     Capacity	Request rate, quota utilization, and 429 rate	Sustained throttling or unexpected growth.
     Decisioning	Latency, error rate, and idempotent replay	Rising 5xx rate or duplicate logical operations.
     Outcomes	Reporting lag and missing correlations	Decisions without observed outcomes.
     Webhooks	Delivery failures and consumer retries	Repeated callback failure or growing backlog.

5. ‌ENTERPRISE plan

   The ENTERPRISE plan is designed for high-volume or highly governed deployments. It may combine custom capacity with formal operational controls, enhanced reporting, environment isolation, certification evidence, support coordination, and contract-specific retention or feature enablement.

   ‌Common ENTERPRISE requirements

   • Custom request and quota policy based on measured workload.

   • Multiple services, business units, merchants, or environments with separate credentials.

   • Formal key-rotation, revocation, and audit procedures.

   • Administrative reporting and tenant-usage visibility.

   • Governance certification and negative tenant-isolation tests.

   • Controlled access to investigation runs or administrative integrations.

   • Defined retention, export, incident-response, and support expectations.

   • Capacity planning for large payment-event batches and sustained decision traffic.

     
     

     ‌Enterprise onboarding questions

     Question	Why it matters
     What is the peak and average request rate?	Capacity should be based on measured traffic, not only monthly totals.
     How many environments and services need keys?	Separate credentials improve isolation, attribution, and rotation.
     Which administrative capabilities are required?	Merchant keys do not automatically authorize /v1/admin/* routes.
     What evidence and retention rules apply?	Audit, outcome, and investigation records may have contractual requirements.
     What support and escalation model is needed?	Operational ownership must be clear before production launch.
     Which capabilities need certification?	Enterprise governance should verify controls through evidence and tests.

     
     

     Enterprise is governed, not merely larger

     The defining difference is not only higher volume. ENTERPRISE is appropriate when scale, contractual controls, security review, operational governance, or administrative integration require a coordinated deployment model.

6. ‌Selecting a usage plan

   Choose a plan from expected behavior and operational requirements, not from the plan name alone. Start with the lowest plan that safely supports the workload, then move when measured usage or governance needs justify the change.

   
   

   1 Estimate Measure event, decision, outcome, and webhook volume.

   2 Classify Identify prototype, production, or governed deployment needs.

   3 Confirm Review actual plan limits and enabled capabilities.

   4 Test Run representative load and failure scenarios.

   5 Approve Document commercial and operational ownership.

   
   

   Decision factor	FREE	PROFESSIONAL	ENTERPRISE
   Lifecycle stage	Evaluation	Production	Production at scale or under formal governance
   Traffic profile	Low and experimental	Regular merchant workload	High, bursty, multi-team, or custom
   Support model	Self-guided or basic onboarding	Defined production support	Coordinated enterprise support and escalation
   Governance	Basic tenant-safe controls	Production controls and monitoring	Formal certification, evidence, and contract policy
   Configuration	Conservative defaults	Production plan settings	Custom or contract- specific settings

   
   

   ‌Questions to answer before selection

   • How many payment events will be submitted per hour, day, and month?

   • Will decisions be requested synchronously, read after ingestion, or both?

   • How quickly will outcomes be reported?

   • What peak burst is expected during billing cycles?

   • How many environments and independent services need credentials?

   • Are administrative investigation, reporting, or governance capabilities required?

   • What retention, audit, export, and support commitments are necessary?

7. ‌Plans, quotas, and rate limits

   A usage plan and a quota are related but not identical. The plan is the commercial policy assignment. Quotas define longer-window usage allowances, while rate limits control short-window request pressure. Endpoint schema limits, such as maximum batch size, remain technical contract rules independent of the plan.

   
   

   Control	Purpose	Example client response
   Plan	Defines commercial policy and available capabilities	Read current assignment; do not infer undocumented features.
   Quota	Limits usage over a billing or policy period	Track utilization and handle exhaustion without data loss.
   Rate limit	Controls request volume over a short window	Back off and honor Retry-After when present.
   Schema limit	Defines valid request shape or batch size	Split requests before sending; do not retry an invalid payload.
   Authorization	Controls endpoint and resource access	Use only approved routes for the authenticated identity.

   
   

   Schema limits remain fixed

   Payment-event ingestion accepts 1 to 10,000 events per request, while the legacy batch retry-decision request accepts up to 500 events. These are request-schema limits, not promised throughput and not automatically increased by a higher plan.

   
   

   ‌Client response to plan or capability denial

   if response.status_code == 403:

   # Authenticated, but the capability is not enabled or permitted. raise CapabilityNotEnabled(response.json())

   
   

   if response.status_code == 429:

   # Capacity or quota enforcement. Use bounded backoff. retry_after = response.headers.get('Retry-After')

1. ‌Changing plans safely

   A plan change should normally be a configuration and commercial change, not an application rewrite. Keep the base URL, credentials, batching behavior, and capability flags external to code so changes can be tested and rolled out safely.

   
   

   1 Review usage Confirm actual volume, peaks, 429 activity, and growth.

   2 Confirm contract Document new limits, features, retention, and support terms.

   3 Test behavior Validate capability and quota metadata in staging.

   4 Activate Apply the plan through approved administration.

   5 Monitor Verify traffic, audit records, and quota behavior after change.

   
   

   ‌Do not assume after an upgrade

   • That every endpoint is newly authorized.

   • That all quotas are unlimited.

   • That schema batch limits changed.

   • That administrative routes accept a merchant API key.

   • That retention applies retroactively.

   • That existing clients can stop handling 429 or 403 responses.

     
     

2. ‌Developer readiness checklist