Kicbac Python SDK

Official Python SDK for the Kicbac payments gateway.

The package provides sync and async clients, typed results, Customer Vault, recurring billing, invoicing, Product Manager, Query API support, and webhook verification.

The transaction resource covers sales, authorizations, credits, validation, offline authorizations, captures, voids, refunds, transaction updates, and partial-payment completion. The Query API includes typed paginated reports and a safe raw read-only report method.

Install

pip install kicbac

Quickstart

import kicbac

client = kicbac.Kicbac()  # reads KICBAC_SECURITY_KEY

result = client.transactions.sale(
    amount="49.99",
    payment_token="tok_from_kicbac_js",
)

if result.ok:
    print(result.transaction_id)
else:
    print("declined", result.response_code, result.message)

Safety model

• Tokenize card and bank data in Kicbac.js hosted fields before calling your server.
• Send payment_token to this SDK, or use the typed gateway-encrypted Apple Pay / Google Pay arguments. Cash sales use payment="cash".
• Raw PAN, merchant-decrypted wallet, and retail track/chip payloads are intentionally outside this SDK's PCI/device scope. Use Kicbac.js or the appropriate device integration instead.
• Pass verified 3-D Secure results through the typed three_ds mapping; do not put them in extra_params.
• response=2 is a typed decline result and should be handled in normal control flow.
• response=3, authentication failures, processor errors, rate limits, validation errors, and transport failures raise typed exceptions.
• transact.php is not idempotent. The SDK only retries charge requests when it can prove no bytes were sent.

Webhooks

Verify against the exact raw request bytes:

import kicbac
from kicbac.errors import SignatureVerificationError, WebhookPayloadError


def handle_webhook(
    raw_body_bytes: bytes,
    signature_header: str | None,
    webhook_signing_key: str,
) -> int:
    try:
        event = kicbac.construct_event(
            raw_body_bytes,
            signature_header,
            webhook_signing_key,
        )
    except (SignatureVerificationError, WebhookPayloadError):
        return 400

    # Process and deduplicate the verified event by event.event_id.
    return 200

The signature header is Webhook-Signature: t=<nonce>,s=<sig>. The signature is HMAC-SHA256 over nonce + "." + rawBody.

Development

cd sdk-python
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest
.venv/bin/mypy --strict src
.venv/bin/ruff check src tests
.venv/bin/ruff format --check src tests
.venv/bin/python -m build

Releases are tagged vX.Y.Z; CI publishes to PyPI via trusted publishing.

The openapi/ directory contains shared public fixtures used by tests. kicbac-js is canonical; CI diffs this copy against kicbac-js@main and fails on drift. Update it by re-copying from kicbac-js.