Skip to main content
View as Markdown

Inttegro Python SDK

The Inttegro Python SDK builds server-side integrations with typed request dataclasses, immutable domain objects, JSON-compatible enums, and Python-native resource namespaces.

Start with MCP

Before writing SDK code, connect your MCP client and ask MCP to design the integration for your Python application. Use the resulting implementation and test plan to guide the code you write with this SDK.

Install

The SDK requires Python 3.10 or newer. Install the package from PyPI:

pip install inttegro
Keep the SDK on the server

Load the secret API key securely from server-side code. Never place the key in browser code, a mobile application, or source control.

Create an async client

Use AsyncInttegroClient in FastAPI, async Django views, Python Workers, and other event-loop applications. Create one client for the application lifetime so its HTTP connection pool can be reused, and close it during shutdown.

import os

import inttegro
from inttegro import AsyncInttegroClient

client = AsyncInttegroClient(
    api_key=os.environ["INTTEGRO_API_KEY"],
)


async def create_order(
    request: inttegro.order.CreateRequest,
) -> inttegro.order.Order:
    return await client.orders.create(request)


async def shutdown() -> None:
    await client.aclose()

Request classes live in singular resource packages, such as inttegro.order.CreateRequest. Returned resources are typed domain objects with attribute access, mapping access, and to_dict().

The main object has the same name as its singular package. Related models and enums stay beside it, so imports and autocomplete remain focused:

from inttegro import payment, product

catalog_product = product.Product.from_dict(product_data)

if catalog_product.type == product.Type.DIGITAL and catalog_product.is_published():
    # Offer the product for sale.
    pass

payment_result = payment.Payment.from_dict(payment_data)

if payment_result.status == payment.Status.REQUIRES_ACTION:
    next_action = payment_result.required_action()

Question methods such as is_paid(), requires_action(), is_terminal(), is_published(), and is_reusable() inspect the current object only. They never make an API request.

For synchronous Django or Flask views, scripts, and jobs, use InttegroClient. Do not call the synchronous client directly from an async handler: it blocks the event loop, and runtimes such as Cloudflare Python Workers cannot offload that work to an OS thread.

See it in a complete app

Use either demo to follow a ticket sale from reservation to Inttegro Checkout:

Both keep the ticket, price, and fulfillment decision on the server and use the Python SDK to create the payable order.

Observability

The global OpenTelemetry provider is used automatically. Pass a provider when the client should use an explicitly managed tracing pipeline:

import os

from inttegro import AsyncInttegroClient
from opentelemetry import trace

client = AsyncInttegroClient(
    api_key=os.environ["INTTEGRO_API_KEY"],
    tracer_provider=trace.get_tracer_provider(),
)

Inttegro emits vendor-neutral OpenTelemetry spans through the provider configured by your application. The SDK does not choose an exporter or observability vendor, and it does not send telemetry by itself.

Each public SDK call creates one CLIENT span named after the logical operation, such as inttegro.orders.create. HTTP attempts, retries, response receipt, decoding, and failures appear as events on that span. W3C trace context is propagated on outbound requests.

Span attributes and data-safety contract

The stable attributes are:

  • inttegro.operation.name, SDK language and SDK version
  • HTTP method and response status when available
  • destination host and the static API route template
  • the safe request identifier returned by the API
  • a low-cardinality failure category such as a timeout

SDK telemetry never records API keys, authorization headers, request or response bodies, customer or payment data, resource identifiers, dynamic URLs, query strings, exception messages, or stack traces.

To turn off Inttegro instrumentation for a client, use telemetry_enabled=False.

Report SDK failures​

Pass an application-owned callback to receive one immutable, typed report after an SDK operation finally fails:

import os

import inttegro
from inttegro import AsyncInttegroClient


def enqueue_error(report: inttegro.ErrorReport) -> None:
    payload = report.to_dict()
    _ = payload  # Forward the payload to your collector or queue.


client = AsyncInttegroClient(
    api_key=os.environ["INTTEGRO_API_KEY"],
    error_reporter=enqueue_error,
)

The default policy reports transport, timeout, decoding, SDK, unknown, and server-side failures. Expected API failures such as normal 4xx responses stay with the caller. Use error_reporting_policy="all" when the collector should receive those failures too. Cancellation is never reported.

When the collector needs a JSON-compatible payload, use report.to_dict().

Report fields and data-safety contract

A report contains:

  • the logical operation, static route, server host, status, duration, and safe request identifier when available
  • safe API error codes and a stable, low-cardinality fingerprint
  • SDK identity, exception type, and active trace identifiers

Reports never contain API keys, authorization headers, request or response bodies, customer or payment data, resource identifiers, dynamic URLs, query strings, exception messages, or stack traces.

Reporting is completely opt-in. Unless error_reporter is configured, the SDK does no reporting-specific timing or metadata preparation, creates no event ID or report object, and serializes nothing. Report construction and collector failures are isolated, so the caller still receives the original SDK failure.

Continue