Help and DocumentationContact Us

ZAHLEN

Chapter 2

Getting Started

Create an account, generate an API key, and select a usage plan

Audience

Merchants | Developers | Integration Engineers

Zahlen API User Guide v1.0

Source baseline: zahlen_deploy_0616A.tar.gz | June 2026

‌Chapter 2 - Getting Started

A successful Zahlen integration begins before the first line of application code. The merchant must establish a tenant, choose an environment, define who may administer credentials, select a usage plan, and decide how identifiers and secrets will be stored. These decisions create the ownership and security foundation for every payment event, retry decision, outcome, and report that follows.

1. ‌Before you begin

   Gather the following information before requesting production access. A small amount of planning here prevents key-sharing, duplicate identifiers, and environment confusion later.

   
   

   Concept	Meaning
   Merchant organization	Legal or operating name, primary technical contact, support contact, and the team responsible for recurring-payment recovery.
   Integration owner	The person accountable for implementation decisions, testing, deployment, and production support.
   Environment plan	The development, staging, and production hostnames and the systems that will call each environment.
   Expected traffic	Estimated payment-event volume, decision volume, batch sizes, peak rate, and outcome-reporting frequency.
   Data mapping	The merchant fields that will populate event IDs, payment tokens, billing cycles, subscriptions, decline codes, issuer details, amounts, timestamps, and processor references.
   Secret storage	The secret manager, deployment system, or protected environment-variable mechanism that will store API keys.
   Retry orchestration	The service that will execute the fixed Day 1, Day 2, Day 6, and Day 16

   
   

   Concept	Meaning
   	retry schedule and report each observed outcome.

   
   

   ‌Recommended onboarding roles

   
   

   Role	Responsibility
   Merchant administrator	Creates or approves the tenant account, assigns administrative access, selects the plan, and governs API keys.
   Application developer	Builds requests, handles responses, stores identifiers, and implements safe retry behavior.
   Integration engineer	Maps payment-system fields, environments, network access, observability, and deployment configuration.
   Security reviewer	Approves secret handling, data minimization, audit requirements, and production access.
   Operations owner	Monitors outcomes, failed integrations, quota pressure, and investigation-run status after launch.

   
   

2. ‌Create a Zahlen account

   A Zahlen account is provisioned within a tenant. The tenant is the durable ownership boundary for merchant data, credentials, quotas, audit records, and administrative resources. The exact registration screen or approval workflow may vary by deployment, so follow the invitation or onboarding process supplied by the Zahlen administrator.

   ‌Account-creation workflow

   
   

   1 Request access Provide merchant, contact, environment, and traffic information.

   2 Tenant provisioned Zahlen creates or confirms the tenant ownership boundary.

   3 User invited An authorized administrator receives account access.

   4 Identity verified Complete password, session, and any required security setup.

   5 Access reviewed Confirm environment, role, merchant context, and administrative permissions.

   
   

   ‌What to verify after sign-in

   • The displayed organization or tenant is the one assigned to your merchant.

   • The hostname clearly identifies development, staging, or production.

   • Your user can reach only the administrative pages required for your role.

   • The merchant or business context shown in the portal is correct.

   • The selected plan and quota information are visible or available from your Zahlen administrator.

   • API-key creation is restricted to authorized administrators.

     
     

     Ownership warning

     Do not work around an incorrect or missing tenant by adding a tenant identifier to a form, query string, or JSON body. Tenant ownership must come from authenticated account or API-key context.

     
     

     ‌Environment separation

     Use separate credentials, hostnames, databases, and operational records for development, staging, and production. A development key should never authenticate against production, and a production key should never be copied into a developer laptop, source repository, test fixture, browser script, or chat message.

     
     

     Concept	Meaning
     Development	Used for local or shared integration work with fictional or approved test data. Failures are expected and should not affect production records.
     Staging	Used for release-candidate testing, contract verification, load rehearsal, webhook validation, and operational readiness checks.
     Production	Used only by approved services with protected secrets, monitored traffic, documented ownership, and an incident response path.

     
     

3. ‌Generate an API key

   Merchant-facing API calls authenticate with the `X-API-Key` header. The key resolves the authorized tenant, merchant, and actor context. It is both a credential and an ownership control, so it must be generated, stored, distributed, rotated, and revoked with the same care as a production password or service credential.

   ‌Key-generation workflow

   
   

   1 Open key controls Use the approved developer portal or administrative key page.

   2 Choose context Select the correct environment and merchant scope.

   3 Name the key Use a service-oriented label such as billing- worker-prod.

   4 Create and capture Copy the secret once into an approved secret manager.

   5 Test and audit Verify authentication, record the key ID, and review activity.

   
   

   The secret value may be displayed only when the key is created. Zahlen should retain a secure hash for validation rather than storing the original secret in retrievable form. Record the non-secret key

   identifier or fingerprint for support and audit purposes, but never record the full key in tickets or application logs.

   ‌Recommended key naming

   
   

   Concept	Meaning
   Service	Identify the calling workload, for example `billing-api`, `retry-scheduler`, or `outcome-reporter`.
   Environment	Include `dev`, `stage`, or `prod` so a credential cannot be mistaken for another environment.
   Owner	Associate the key with a team or system owner, not an individual developer when possible.
   Purpose	Use separate keys for independent services so access and activity can be isolated and revoked safely.

   
   

   ‌Store the key securely

   • Place the key in a managed secret store or protected runtime environment variable.

   • Restrict read access to the service identity that needs the credential.

   • Inject the key at deployment time rather than compiling it into the application.

   • Do not expose the key in client-side JavaScript, a browser, or a mobile application.

   • Redact the key from exception messages, HTTP tracing, screenshots, and support bundles.

     

     

     Treat the API key as secret material

• Create separate keys for separate services and environments instead of sharing one universal key.

‌Configure the client

export ZAHLEN_BASE_URL='https://api.example.com' export ZAHLEN_API_KEY='zk_live_REPLACE_ME'

curl -sS "$ZAHLEN_BASE_URL/v1/version" \

-H "X-API-Key: $ZAHLEN_API_KEY"

Use the base URL provided for the selected environment. Do not hard-code a placeholder hostname or production secret in source code. Some diagnostic routes may be public, but successful access to a health endpoint does not prove that the key is authorized for commercial operations.

1. ‌Select a usage plan

   Zahlen supports FREE, PROFESSIONAL, and ENTERPRISE plan concepts. Exact quotas, enabled features, retention, support terms, and certification requirements are deployment- or contract-specific. Select the plan based on the merchant workload and governance needs, then read the active limits from the developer portal or administrative controls instead of hard-coding assumed values.

   
   

   Plan	Typical fit	Integration guidance
   FREE	Evaluation, classroom-style learning, prototypes, and low-volume integration testing.	Use realistic error handling from the beginning. Expect conservative quotas and avoid treating the plan as a production guarantee.
   PROFESSIONAL	Production merchant integrations with regular event, decision, and outcome traffic.	Monitor usage, use batch endpoints where appropriate, and establish key rotation, alerting, and support ownership.
   ENTERPRISE	High-volume, multi-service, or governed deployments requiring custom controls.	Coordinate custom quotas, retention, administrative access, certification evidence, reporting, and operational support.

   
   

   ‌Plan-selection questions

   • How many payment events will be submitted per day and during peak billing windows?

   • Will the client use single-event calls, batches, direct decision calls, or all three?

   • How quickly must a retry decision be returned to the merchant workflow?

   • How many independent services or environments require separate API keys?

   • What retention, reporting, audit, and governance evidence is required?

   • Will enterprise operators need access to investigation runs or administrative reporting?

   • What support response and change-management process is required for production?

     
     

     Plan names are not capability guarantees

     Do not assume that every tenant on the same named plan has identical features or limits. Use the active plan, capability metadata, quota configuration, and explicit API responses as the source of truth.

     
     

2. ‌Prepare stable identifiers

   Before sending test traffic, decide how the merchant system will create and store the identifiers that connect the complete recovery workflow. Stable identifiers make requests repeat-safe, simplify support, and preserve traceability across payment systems and Zahlen.

   
   

   Concept	Meaning
   `event_id`	Created by the merchant. Use one stable identifier for one payment

   
   

   Concept	Meaning
   	event; do not recycle it for unrelated events.
   `payment_token` or `token`	A merchant-side token that identifies the payment instrument without exposing a full card number.
   `subscription_id`	The merchant subscription or recurring-account reference.
   `billing_cycle_id`	The billing-cycle reference used by the legacy decision contract.
   `Idempotency-Key`	A stable key for one logical operation on routes that support idempotency. Reuse it only when retrying the same operation.
   Returned IDs	Store batch, upload-job, request, and decision IDs returned by Zahlen for tracing and outcome correlation.

   
   

   ‌Map the fixed retry schedule

   The merchant scheduler should represent the four canonical attempts explicitly. Do not collapse them into an ambiguous retry counter. Store both the attempt number and the intended day in the recovery cycle.

   
   

   Attempt	Scheduled day	Integration meaning
   1	Day 1	Initial recovery attempt or first scheduled retry in the Zahlen recovery cycle.
   2	Day 2	Second attempt after the first-day evidence is available.
   3	Day 6	Third attempt after a longer waiting interval.
   4	Day 16	Final scheduled attempt in the canonical recovery sequence.

   
   

3. ‌Verify connectivity

   Begin with a health check against the exact environment hostname supplied by Zahlen. A health response verifies DNS, TLS, routing, and service availability. It does not verify merchant authorization.

   curl -sS "$ZAHLEN_BASE_URL/v1/health" | python -m json.tool

   
   

   A successful response contains service status, service name, API version, and server time. Record the environment and response during deployment verification.

   ‌Verify the deployed version

   curl -sS "$ZAHLEN_BASE_URL/v1/version" \

   -H "X-API-Key: $ZAHLEN_API_KEY" | python -m json.tool

   The version response can include API version, application version, rules version, and playbook version. These values are useful during support and change-management investigations.

4. ‌Send the first authenticated request

   Use fictional or approved test data. The following request submits one payment event. The request model requires the `events` array and each event requires a non-empty `event_id`. Unknown top-level event fields are rejected by strict schema validation.

   curl -sS -X POST "$ZAHLEN_BASE_URL/v1/payment-events" \

   -H 'Content-Type: application/json' \

   -H "X-API-Key: $ZAHLEN_API_KEY" \

   -d '{

   "source": "getting_started", "events": [{

   "event_id": "evt_20260616_0001", "decline_code": "51",

   "issuer_bin": "411111",

   "amount_minor": 2999, "currency": "USD", "attempt_number": 1,

   "attempt_day_in_cycle": 1, "event_timestamp": "2026-06-16T12:00:00Z", "payment_token": "tok_test_001", "subscription_id": "sub_test_001"

   }]

   }'

   
   

   A successful ingestion response returns identifiers and counts such as `payment_event_batch_id`,

   `upload_job_id`, received-event count, valid and invalid row counts, status, source, and timestamps. Save these identifiers immediately.

   
   

   Use only safe test data

   Never send a full primary account number, CVV, password, raw bank credential, or production customer secret in a tutorial request. Use merchant-side tokens and the minimum evidence needed for decisioning.

   
   

5. ‌Readiness checklist

   • The correct tenant and merchant account are provisioned.

   • Development, staging, and production hostnames are documented.

   • An authorized administrator owns API-key creation and revocation.

   • The API key is stored in a secret manager and absent from source control.

   • The active usage plan and current quotas are known.

   • Event, token, subscription, billing-cycle, and idempotency identifiers are defined.

   • The billing workflow can execute and report Day 1, Day 2, Day 6, and Day 16 attempts.

   • Health and version checks succeed in the selected environment.

   • The first authenticated payment-event request succeeds with fictional test data.

   • Returned batch and upload-job identifiers appear in application logs.

     
     

6. ‌Common onboarding mistakes

   
   

   Concept	Meaning
   Using one key everywhere	Creates a large blast radius and makes service-level activity difficult to audit. Use separate keys by environment and workload.
   Hard-coding plan limits	Plan configuration may differ by deployment or contract. Read current quota and capability information.
   Treating health as authorization	A public or reachable health endpoint proves connectivity, not permission to use merchant routes.
   Sending ownership fields	Do not try to select a tenant in the request body. Ownership comes from authenticated context.
   Logging secrets	HTTP debugging and exception traces can expose `X-API-Key`. Redact authorization material.
   Losing returned IDs	Without batch, upload-job, request, and decision IDs, support and outcome correlation become difficult.
   Ignoring the fixed schedule	The recovery workflow must preserve the canonical Day 1, Day 2, Day 6, and Day 16 attempt sequence.

   
   

7. ‌Chapter summary

   • A Zahlen account is provisioned within a tenant, which is the ownership boundary for data and controls.

   • Merchant-facing calls use a securely generated API key in the `X-API-Key` header.

   • Keys should be separated by environment and service, stored in a secret manager, and logged only by safe identifier or fingerprint.

   • Stable identifiers connect payment events, decisions, outcomes, investigation runs, and support records.

   • The merchant integration must support Zahlen's fixed retry schedule: Day 1, Day 2, Day 6, and Day 16.

   • Connectivity and authenticated ingestion should be verified before broader integration work begins.