prava-sdk 0.1.0

Official Python server-side SDK for Prava Payments

Prava Python SDK

Typed server-side Python SDK for Prava Payments.

Documentation · Source

The SDK creates payment sessions, manages enrolled cards, retrieves one-time payment credentials, and reports checkout outcomes. Card collection still happens on Prava's hosted surface or through the browser @prava-sdk/core package—your Python server must never collect a cardholder's raw card number.

Installation

pip install prava-sdk

Python 3.10 or newer is required.

The complete SDK guide is available in docs/, with runnable programs in examples/.

Quick start

from decimal import Decimal

from prava_sdk import PravaClient

client = PravaClient("sk_test_xxx")

session = client.sessions.create(
    user_id="user_123",
    user_email="[e-mail]",
    total_amount=Decimal("49.99"),
    currency="USD",
    purchase_context=[
        {
            "merchant_details": {
                "name": "Example Store",
                "url": "https://merchant.example",
                "country_code_iso2": "US",
            },
            "product_details": [
                {
                    "description": "Example product",
                    "unit_price": "49.99",
                    "product_id": "sku_123",
                    "quantity": 1,
                }
            ],
        }
    ],
    integration_type="full_checkout",
    callback_url="https://app.example/payments/complete",
)

# Send the cardholder to session.iframe_url. After card entry and passkey approval:
result = client.sessions.wait_for_payment_result(session.session_id)
line_item = result.transactions[0].line_items[0]

card_number = line_item.token.get_secret_value() if line_item.token else None
dynamic_cvv = line_item.dynamic_cvv.get_secret_value() if line_item.dynamic_cvv else None

# Use the one-time credentials at the merchant checkout, then always report the outcome.
client.sessions.report_status(
    session.session_id,
    txn_ref_id=line_item.txn_ref_id,
    txn_status="APPROVED",
)

client.close()

The secret key can instead be supplied through PRAVA_SECRET_KEY. sk_test_* keys automatically use https://sandbox.api.prava.space; sk_live_* keys use https://api.prava.space.

Use the client as a context manager to guarantee cleanup:

from prava_sdk import PravaClient

with PravaClient("sk_test_xxx") as client:
    cards = client.cards.list(customer_id="user_123")

Async client

AsyncPravaClient exposes the same grouped resources and method arguments:

from prava_sdk import AsyncPravaClient

async with AsyncPravaClient("sk_test_xxx") as client:
    result = await client.sessions.wait_for_payment_result(
        "ses_123",
        timeout=300,
        poll_interval=2,
    )

API

Sessions

• client.sessions.create(...)
• client.sessions.revoke(session_id)
• client.sessions.get_payment_result(session_id)
• client.sessions.wait_for_payment_result(session_id, timeout=300, poll_interval=2)
• client.sessions.report_status(session_id, ...)

The polling helper returns as soon as the result status becomes awaiting_result, completed, or failed. It raises PravaPollingTimeoutError if the session remains pending past the timeout.

Cards

• client.cards.list(customer_id=..., status="active", include_card_art=False)
• client.cards.delete(customer_id=..., card_id=..., reason="OTHER")

Only non-sensitive card metadata is returned by card-management endpoints.

Errors

All failures derive from PravaError. API exceptions expose code, message, status_code, details, and response_id (from the X-Response-ID response header):

from prava_sdk import PravaError

try:
    client.sessions.revoke("ses_missing")
except PravaError as exc:
    print(exc.code, exc.response_id)

The SDK provides dedicated authentication, validation, not-found, invalid-state, rate-limit, transport, request-timeout, and polling-timeout exception types. Requests are not retried automatically because the API does not currently document idempotency keys.

Security

• Never use sk_test_* or sk_live_* keys in browsers, mobile apps, logs, or version control.
• Never collect or send a cardholder's underlying card number through this SDK.
• Payment-result token and dynamic_cvv values are Pydantic SecretStr fields and are redacted from normal model representations. Retrieve them only immediately before checkout.
• Always call report_status with APPROVED or DECLINED after attempting checkout.

See the API reference, error catalog, and sandbox guide for the complete server contract.

Package architecture

The SDK is organized as a standalone Python library:

prava_sdk/
├── client.py          # Small public sync and async client facades
├── resources/         # Session and card endpoint groups
│   └── _base.py       # Shared resource contracts and validation boundary
├── models/            # Pydantic requests, responses, and enums
├── _config.py         # Secret-key and environment resolution
├── _transport.py      # Shared HTTP, JSON, and response handling
└── errors.py          # Public exception hierarchy

The JavaScript SDK is not a runtime or build dependency. It only handles browser-side card collection and is excluded from Python source and wheel distributions.

Development

uv sync --extra dev
uv run ruff check .
uv run mypy
uv run pytest
uv run mkdocs build --strict
uv run python -m build