Skip to main content

Alogram PayRisk Logo

Alogram PayRisk SDK for Python

PyPI version License

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:

  1. Anchor pre-order signals using sessionId and deviceId.
  2. Correlate those signals during the check_risk call.
  3. Handoff to the server-minted paymentIntentId for 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 AlogramRiskClient or 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 httpx session "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 AlogramRiskClient for backend operations. Access the authoritative blended score via the decision_score attribute of the response. Use the idempotency_key parameter 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)

Source distribution for alogram-payrisk 0.3.4
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)

Table of built distributions (wheels) for alogram-payrisk 0.3.4
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page