Payment API

Install RC2. Run recovery.

Choose one language for the free synthetic HTTP exercise. Python is published on PyPI; JavaScript uses the pinned GitHub release while npm publication is pending. No HALTSEAL account or real funds are needed.

python3 -m venv .venv
. .venv/bin/activate
python -m pip install haltseal-payments==0.2.0rc2
python -m haltseal_payments_sdk.sandbox --output python-sandbox.json

npm install --ignore-scripts --no-audit --no-fund \
  https://github.com/HALTSEAL/payments-sdk/releases/download/v0.2.0-rc.2/haltseal-payments-0.2.0-rc.2.tgz
npx --no-install haltseal-payments-demo --output javascript-sandbox.json

Each demo connects to fixed HTTP fixtures at haltseal.com. No HALTSEAL account, provider credentials or real funds. Use a new output filename for each run; existing records are never overwritten.

Expected: original lookup → UNKNOWN HOLD → closure → stale HOLD → fresh ACCEPT → PAID REFUSE. Two synthetic dispatches. Zero original-lookup redispatches.

Release files, checksums and the optional offline comparison are available separately. SDK v2 response guards align with the RC5 API profile. The browser exercise retains its frozen RC4 clients. These fixed fixtures do not qualify the payment kernel or a native provider.

Start with the free Workspace Sandbox. SDK fixtures, local evaluation and installed runtime checks have separate setup and evidence scopes. Optional assistance is separately agreed. See current pricing and qualification.

Set up the local evaluator.

Install the RC2 client for your language using the commands above. Optional offline archives and their checksums are on the SDK release page. Request the complete evaluator for a configured local gateway and signed source fixture before running these examples. The free Payment Control Lab is a separate diagnostic tool you can run immediately.

Use a provisioned bearer key from your backend. Its role and customer scope come from the key. Keep API and issuer keys out of browser code. The evaluator uses http://127.0.0.1:8790; there is no public hosted payment-kernel origin. The separate SDK sandbox hosts only fixed synthetic HTTP fixtures; its short-lived demo key cannot access a payment evaluator.

Installation supplies a client, not an account or running gateway. Keep the fixture demo separate from your configured evaluator and its provisioned key.

Bind the real payment

An issuer-signed source binds the organization, workflow, canonical business reference, payer, beneficiary, currency and full principal. A source revision cannot change those economics. The trusted source owner must establish which records describe the same real obligation.

The source import is POST /v1/payment-obligations. It returns an obligation_id after accepting the source record. JavaScript must send the issuer’s original signed JSON string without parsing or rewriting nanosecond integers.

Submit one exact attempt.

This example assumes the evaluator is running and the signed source has been imported. The evaluator supplies obligation_id, api_key and the current approval_revision. Routes A, B and C are configured local fixtures.

from haltseal_payments_sdk import Client

client = Client("http://127.0.0.1:8790", api_key)
result = client.create_attempt(
    obligation_id,
    operation_id="cash-4822-original",
    route="A",
    approval_revision=approval_revision,
)
# Inspect result["decision"] and the retained attempt state.
# ACCEPT does not establish that the payment settled.

The API takes the full amount and immutable provider payload from retained state. Clients do not supply a new amount, beneficiary or provider account on each attempt.

Keep the operation ID. An exact repetition returns the recorded decision without redispatch. Changing the request under that ID produces HOLD for request-reuse mismatch.

Endpoint reference.

All protected routes use bearer authentication. The published RC4 OpenAPI baseline contains exact request schemas and parameter names.

Amounts use integer minor units. Timestamps in signed sources use integer nanoseconds. Unknown fields and duplicate JSON keys are refused.

Recover the original. Preserve its principal.

1. Lost create reply: look up the retained operation ID. If lookup is absent or fails, retain that identity and resolve the uncertainty before another financial action. Absence is not proof of no payment.
2. Original UNKNOWN: the full principal remains reserved. A replacement is HOLD.
3. Original PAID: the obligation is consumed. Another full-principal payment is REFUSE.
4. Original CLOSED: authoritative evidence must establish that the exact original has not paid and can no longer pay. Import a newer signed approval issued after retained closure, then submit a fresh exact replacement for validation.

Cancellation submission, a timeout, a fee refund or final AI-job cost does not establish payment closure. Recovery performs original lookup and evidence checks; it does not resend financial creation.

Before a replacement, the kernel reobserves closed originals and checks the current approval, expiry, revocation, route and full amount. Closure restores eligibility for a fresh check, not automatic permission to pay.

Read the business result.

HTTP 200 can contain ACCEPT, HOLD or REFUSE. Inspect decision and current attempt state. A historical ACCEPT is a record of an earlier decision, not a new grant or proof of settlement.

UncertainDispatch retains the original identity, exact request fingerprint, API origin and next recovery action. TransportError represents an uncertain read; ValidationError is rejected locally before sending. The clients bound responses at 1 MiB, refuse redirects and never retry a financial call automatically.

Persist identity and the exact request before invoking the SDK. Python exposes error.recovery.to_dict(); Node exposes frozen error.recovery with the same JSON fields. A request fingerprint is correlation, not approval or a payment lookup key. Read the preserved RC4 failure contract and RC4 customer acceptance.

Evaluate locally. Qualify your workflow.

This version evaluates synthetic own-account USD fixtures on one physical host. Native provider calls, customer installations and independent operators remain unqualified. It is not a managed production service. Backup restoration, migration and distributed recovery are not qualified. Read the public operations and recovery guide for safe customer actions; operator procedures accompany the evaluator under agreed review scope.

Production activation requires reviewed provider products, authoritative closure evidence, complete release-path coverage, retained history and agreed deployment and recovery ownership. An unconnected bank portal or direct provider call remains outside the boundary.

You can start developer evaluation without buying an assessment. A scoped paid workflow assessment is available when your team needs help reviewing actual paths, evidence and decision responsibility. Customer acceptance and technical qualification govern any enforcement.