Alogram PayRisk SDK for Python
The official Python client for the Alogram PayRisk Engine.
Alogram PayRisk is a decision management and risk orchestration engine for global commerce. It fuses machine learning, behavioral analytics, and deterministic business rules into a high-fidelity scoring pipeline designed for enterprise scale and auditability.
🧠 The Three-Expert Architecture
The SDK provides unified access to three specialized risk experts:
- Risk Scoring: Real-time assessment and decision orchestration for purchases.
- Signal Intelligence: Ingestion of behavioral telemetry and payment lifecycle events.
- Forensic Data: Deep visibility into historical assessments and decision transparency.
🔐 Security: Trust Boundaries
Alogram enforces a strict separation between client-side telemetry and server-side decisioning.
| Client Type | Key Prefix | Environment | Capabilities |
|---|---|---|---|
AlogramPublicClient |
pk_... |
Browser / Mobile | Ingestion only. Cannot perform risk checks or view scores. |
AlogramRiskClient |
sk_... |
Secure Backend | Full access. Authorized for risk decisions and forensic retrieval. |
🔄 Full Lifecycle Integration
A best-in-class Alogram integration follows the three-step lifecycle:
from alogram_payrisk import AlogramRiskClient
from payrisk_v1 import CheckRequest, PaymentEvent
# 1. Initialize the Secret Client (Backend Only)
with AlogramRiskClient(api_key="sk_live_...", tenant_id="tid_mycorp") as client:
# 2. Assessment: Call before charging the customer
decision = client.check_risk(CheckRequest(...))
if decision.decision == "approve":
# Process payment via your gateway...
# 3. Lifecycle: Send the outcome back to Alogram
client.ingest_event(PaymentEvent(
payment_intent_id=decision.payment_intent_id,
event_type="authorization",
outcome={"approved": True}
))
🚀 High-Performance Integration
- 🏢 Smart Client Architecture: Specialized clients for server-side (
AlogramRiskClient) and public-facing (AlogramPublicClient). - 🛡️ Automated Identity: Injects
x-api-key,Authorization, and tenant headers automatically. - 🔄 Built-in Resiliency: Automatic exponential backoff and jittered retries (powered by
tenacity). - 🕵️ Native Observability: Built-in OpenTelemetry tracing for monitoring risk decision latency and outcomes.
- 🧩 Type Safe: Built with Pydantic v2 and full PEP 561 compliance (
py.typed).
📦 Installation
pip install alogram-payrisk
🛠️ Quick Start
1. Evaluate Risk (Risk Scoring Expert)
Assess a purchase in real-time. This invokes the authoritative scoring pipeline.
from alogram_payrisk import AlogramRiskClient, CheckRequest, Purchase, Identity
client = AlogramRiskClient(api_key="sk_live_...", tenant_id="tenant_123")
# Perform the check via the Risk Scoring expert
decision = client.check_risk(CheckRequest(
purchase=Purchase(amount=99.99, currency="USD"),
identity=Identity(email="customer@example.com")
))
print(f"Decision: {decision.decision} | Score: {decision.decision_score}")
2. Ingest Lifecycle Events (Signal Intelligence Expert)
Stream payment lifecycle updates to the Engine for continuous model training.
from alogram_payrisk import PaymentEvent, PaymentOutcome, PaymentAuthorizationOutcome
client.ingest_event(PaymentEvent(
event_type="authorization",
payment_intent_id="pi_123...",
amount=99.99,
currency="USD",
outcome=PaymentOutcome(
authorization=PaymentAuthorizationOutcome(approved=True, responseCode="00")
)
))
🔄 3. Full Lifecycle Workflow
For a complete end-to-end example showing how to correlate client-side signals, risk scoring, and fraud labeling, see: 👉 examples/full_lifecycle_workflow.py
This workflow demonstrates how to:
- Anchor pre-order signals using
sessionIdanddeviceId. - Correlate those signals during the
check_riskcall. - Handoff to the server-minted
paymentIntentIdfor post-order events (Auth, Capture, Chargeback).
🚀 High-Performance Integration
To ensure sub-second risk assessment latencies and handle high-volume signal telemetry efficiently, please adhere to these network best practices:
- Persistent Client (Mandatory): Maintain a single, global instance of the
AlogramRiskClientor use it as a Context Manager.- Anti-pattern: Creating a new client for every request forces a fresh TCP/TLS handshake.
- Best Practice: Reuse the client to keep the underlying
httpxsession "hot."
- HTTP/2 Multiplexing: The SDK natively supports HTTP/2. By reusing the client, multiple requests (e.g., several signals) are automatically multiplexed over a single persistent pipe, eliminating connection management overhead.
🛡️ Error Handling & Resiliency
The SDK distinguishes between transient network issues and validation errors.
from alogram_payrisk.exceptions import ValidationError, AlogramError
try:
decision = client.check_risk(request)
except ValidationError as e:
# ❌ Handle invalid input (e.g., invalid BIN or malformed email)
print(f"Validation Failed: {e.body}")
except AlogramError as e:
# 🚨 Handle generic API or Authentication errors
print(f"API Error [{e.status}]: {e.message}")
🕵️ Observability (OpenTelemetry)
The SDK automatically detects OpenTelemetry. If present, it creates spans for all API calls.
from opentelemetry import trace
# Spans will automatically include 'alogram.decision' and 'alogram.trace_id'
with trace.get_tracer(__name__).start_as_current_span("checkout"):
decision = client.check_risk(request)
🏗️ Environments
| Environment | Base URL | Key Type |
|---|---|---|
| Production | https://api.alogram.ai |
sk_live_... |
| Sandbox | https://api-sandbox.alogram.ai |
sk_test_... |
| Local | http://localhost:8080 |
test |
🤖 For AI Agents
If using an AI agent (ChatGPT, Claude, Gemini) for integration, provide this context:
"Use the Alogram PayRisk Python SDK. Always prefer the
AlogramRiskClientfor backend operations. Access the authoritative blended score via thedecision_scoreattribute of the response. Use theidempotency_keyparameter for all write operations."
⚖️ License
Apache License 2.0. See LICENSE for details.
Metadata
Release files for alogram-payrisk 0.3.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| alogram_payrisk-0.3.4.tar.gz | 85.4 kB | With provenance | Details for alogram_payrisk-0.3.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| alogram_payrisk-0.3.4-py3-none-any.whl | Python 3 | none | any | Details for alogram_payrisk-0.3.4-py3-none-any.whl |
Total release size: 315.8 kB
Release files / alogram_payrisk-0.3.4.tar.gz
| Download URL | alogram_payrisk-0.3.4.tar.gz |
|---|---|
| Size | 85.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4ce5b9708c38ff534c91817f7637e630ed5e3da2f2a06de2537ba58a50265a83
|
|
BLAKE2b-256 checksum How to use checksums |
55ab1b89ef812628fae4669c0b36464e49c25a44eb8ed2c196c1e9f042ddcadc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.
Transparency logRelease files / alogram_payrisk-0.3.4-py3-none-any.whl
| Download URL | alogram_payrisk-0.3.4-py3-none-any.whl |
|---|---|
| Size | 230.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3d582627ead2d66551fde88683d992d369fbe56d1a6dd8bf2ea96b70a77c4cde
|
|
BLAKE2b-256 checksum How to use checksums |
212bbc8f0f33db2b161586087577fa0b223d31f6b8ee06857b8151a7f9ecc37a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.
Transparency logSecurity for alogram-payrisk 0.3.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for alogram_payrisk-0.3.4.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.