validpay 1.1.0

Official ValidPay Python SDK — client-side AES-256-GCM encryption + ValidPay API client

ValidPay Python SDK

Official Python SDK for the ValidPay document verification API. Provides client-side AES-256-GCM encryption and a thin client around the ValidPay HTTP API.

The encryption format is wire-compatible with the Node.js SDK: a payload encrypted by the Python SDK can be decrypted by the Node SDK and vice versa.

Install

pip install validpay

For physical-binding support (Patent F — image-based binding zones), install the optional extras:

pip install validpay[binding]

Requires Python 3.9+.

Quick start

from validpay import ValidPayClient

client = ValidPayClient(api_key="vp_live_xxx")

# Create a single intent — the payload is encrypted locally before
# anything leaves your process. Only the ciphertext is sent to ValidPay.
# Split-key protection (Patent C) is the default since 1.1.0: result.key
# is Share A of the AES key; Share B lives on the ValidPay server. The
# full decryption key never exists on any single system.
result = client.create_intent(
    document_type="check",
    payload={"payee": "John Doe", "amount": 1500.00, "check_number": "10042"},
)
print(result.retrieval_id)  # vp_abc123def456
print(result.key)           # base64 key Share A — embed in the QR / deliver out-of-band

# Create up to 100 intents in one round trip.
results = client.create_intent_batch([
    {"document_type": "check", "payload": {"payee": "Alice", "amount": 500}},
    {"document_type": "check", "payload": {"payee": "Bob",   "amount": 750}},
])
for r in results:
    print(r.retrieval_id, r.key)

# Verify (retrieve + decrypt). No API key required for this endpoint.
verification = client.verify_intent(
    retrieval_id="vp_abc123def456",
    key=result.key,
)
print(verification.payload)         # decrypted dict
print(verification.issuer)          # "Acme Corp"
print(verification.issuer_verified) # True
print(verification.status)          # "active"

Time-Locked Verification (Patent D)

Restrict when a document can be verified by specifying a validity window:

from datetime import datetime, timezone, timedelta

result = client.create_intent(
    document_type="check",
    payload={"payee": "Jane Doe", "amount": 1500.00},
    valid_from=(datetime.now(timezone.utc) + timedelta(hours=1)).isoformat(),
    valid_until=(datetime.now(timezone.utc) + timedelta(days=30)).isoformat(),
)

# Later, when verifying:
verified = client.verify_intent(result.retrieval_id, result.key)
print(verified.time_lock_status)  # "valid", "not_yet_valid", or "expired"
print(verified.valid_from)        # ISO-8601 timestamp or None
print(verified.valid_until)       # ISO-8601 timestamp or None

Time-lock status is informational — the SDK always returns the decrypted payload regardless of the time window. Your application decides how to handle not_yet_valid or expired results. The server stores the timestamps but never enforces them; this preserves the blind intermediary model (the server never decides whether a document is "still good").

The same valid_from / valid_until keyword arguments are accepted by create_intent_batch (per-item) and create_selective_intent.

Split-key intents (Patent C) — the default

All documents created with SDK v1.1+ use split-key by default: the AES key is split into two XOR shares — Share A is returned to the caller (typically embedded in the QR code), Share B is stored server-side. Neither share alone can decrypt the payload, so the full decryption key never exists on any single system.

result = client.create_intent(
    document_type="ssn_card",
    payload={"ssn": "123-45-6789"},
)
# result.key is Share A — verify_intent pairs it with Share B automatically.

verified = client.verify_intent(result.retrieval_id, result.key)
print(verified.payload)

Backward compatibility

• create_intent(..., split_key=False) gives the legacy single-key flow (the returned key is the full AES key).
• create_split_key_intent() is a deprecated alias for create_intent() — 1.0.x code keeps working, with a DeprecationWarning.
• verify_intent detects legacy vs split-key intents from the API response, so it verifies both; verify_split_key_intent() also still works.

Selective disclosure (Patent E)

Each field is encrypted with its own per-field key. A disclosure policy maps role names to the fields that role may decrypt. A full role with access to every field is added automatically.

result = client.create_selective_intent(
    document_type="check",
    payload={"payee": "Alice", "amount": 1500.00, "memo": "rent"},
    disclosure_policy={"bank": ["amount"], "auditor": ["amount", "payee"]},
)

# Bank sees only 'amount'; other fields come back as REDACTED markers.
verified = client.verify_selective_intent(result.retrieval_id, result.key, role="bank")
print(verified.payload)

create_selective_intent accepts split_key=True to combine Patents C + E.

Revocation (Patent H — Blind Revocation)

Issuers can revoke or reinstate an intent without decrypting it. Verifiers of a revoked intent receive status="revoked" and no encrypted payload.

client.revoke_intent("vp_abc123def456", reason="Stop payment")
client.reinstate_intent("vp_abc123def456", reason="False alarm")

history = client.get_revocation_history("vp_abc123def456")
for event in history:
    print(event["action"], event["reason"], event["performed_at"])

API

ValidPayClient(api_key, *, base_url=..., timeout=30.0, session=None)

• api_key — your ValidPay API key (required for create endpoints).
• base_url — defaults to https://api.validpay.com.
• timeout — per-request timeout in seconds.
• session — optionally provide a requests.Session for connection pooling, custom adapters, or mocking in tests.

client.create_intent(document_type, payload, *, split_key=True) -> CreateIntentResult

Encrypts payload (any JSON-serializable value) under a freshly generated AES-256 key and registers it with ValidPay. Returns the retrieval id and the key material: Share A of the split key by default (Share B goes to the server; neither alone decrypts), or the full AES key with split_key=False. The full key is never sent to ValidPay — hand the returned key off out-of-band to whoever needs to verify the intent.

client.create_intent_batch(intents) -> list[CreateIntentResult]

Bulk version. intents is an iterable of mappings shaped {"document_type": str, "payload": Any}, with 1–100 items. Each intent gets its own unique key. Result order matches input order.

client.verify_intent(retrieval_id, key) -> VerifyIntentResult

Fetches the intent (public endpoint, no API key required), decrypts the payload locally, and returns issuer metadata + the decrypted payload.

Errors

All SDK and API errors are raised as ValidPayError, which exposes:

• code — machine-readable code (e.g. "unauthorized", "not_found", "decryption_failed", "invalid_key", "network_error").
• status — HTTP status when the error came from the API.
• details — raw error body / extra context when available.

Low-level crypto

For advanced use cases the encryption primitives are exported directly:

from validpay import generate_key, encrypt, decrypt

key = generate_key()
blob = encrypt('{"hello": "world"}', key)
assert decrypt(blob, key) == '{"hello": "world"}'

Wire format: base64(iv[12] || authTag[16] || ciphertext).

Development

pip install -e ".[dev]"
pytest

License

MIT — see LICENSE.