Jibit IR SDK

Unofficial Python SDK for Jibit APIs.

Jibit IR SDK provides a typed, secure, framework-independent client for Jibit payment, transfer, inquiry, identity, KYC, direct-debit, SMS, and contract-signing APIs. Django integration is available as an optional extra.

It is not affiliated with, endorsed by, or sponsored by Jibit.

Official service-provider website: jibit.ir

معرفی فارسی

Jibit IR SDK یک کتابخانهٔ مستقل و غیررسمی پایتون برای ارتباط ساخت‌یافته و امن با وب‌سرویس‌های جیبیت است. این پکیج تلاش می‌کند استفاده از سرویس‌های پرداخت، انتقال وجه، استعلام، احراز هویت، برداشت مستقیم، پیامک و امضای قرارداد را در پروژه‌های Python و Django ساده‌تر کند.

این پروژه محصول رسمی جیبیت نیست و توسط جیبیت پشتیبانی یا تأیید نشده است. برای آشنایی با شرکت، دریافت دسترسی و مشاهدهٔ اطلاعات رسمی سرویس‌ها به وب‌سایت رسمی جیبیت مراجعه کنید.

امکانات اصلی پکیج:

• دریافت، نگهداری و تمدید خودکار توکن به‌صورت مستقل برای هر سرویس؛
• مدل‌های ورودی و خروجی typed با اعتبارسنجی پیش از ارسال درخواست؛
• مدیریت خطاهای شبکه، احراز هویت، اعتبارسنجی و خطاهای تجاری؛
• retry محافظه‌کارانه و جلوگیری از ارسال مجدد ناامن عملیات مالی؛
• لاگ ساخت‌یافته همراه با حذف یا پوشاندن اطلاعات حساس؛
• پشتیبانی اختیاری از Django Cache و Redis برای نگهداری توکن؛
• دسترسی به سرویس‌های مختلف از طریق یک JibitClient ساده و یکپارچه.

برای نصب پکیج از PyPI:

python -m pip install jibit-ir-sdk

برای استفاده در Django:

python -m pip install "jibit-ir-sdk[django]"

پس از قرار دادن تنظیمات در settings.py می‌توان client مشترک پروژه را به شکل زیر دریافت کرد:

from jibit.django import get_jibit_client

client = get_jibit_client()

کلیدها و رمزهای سرویس را در سورس پروژه قرار ندهید. آن‌ها را از environment variables یا یک secret manager بخوانید. همچنین timeout یک عملیات مالی به معنی ناموفق بودن قطعی آن نیست؛ پیش از ارسال مجدد، وضعیت درخواست را با سرویس inquiry یا reconciliation مربوط بررسی کنید.

Design goals

• A concise high-level API with access to raw responses when needed.
• Automatic, service-scoped token acquisition and refresh.
• Conservative retry behavior for financial operations.
• Typed request and response models with early input validation.
• Structured English-language logging with strict redaction.
• Framework-independent core with optional Django and Redis integrations.
• Explicit documentation of verified, incomplete, and unsupported API behavior.

Supported service families

See the API support matrix for operation-level verification status.

Installation

Install the package from PyPI:

python -m pip install jibit-ir-sdk

Optional integrations:

python -m pip install "jibit-ir-sdk[django]"
python -m pip install "jibit-ir-sdk[redis]"

Python 3.10 through 3.13 are supported. Django 5.2 through 6.0 is supported through the optional django extra. The core package does not install Django or Redis.

Intended usage

from jibit import JibitClient

client = JibitClient.from_config(
    {
        "payment_gateway": {
            "api_key": "<read-from-a-secret-store>",
            "secret_key": "<read-from-a-secret-store>",
        }
    }
)

purchase = client.payment_gateway.create_purchase(
    amount=100_000,
    callback_url="https://example.com/payments/callback/",
    client_reference_number="order-123",
)

print(purchase.data.purchase_id)
print(purchase.data.psp_switching_url)

Credentials must come from environment variables or a secrets manager. The SDK never logs credentials, authorization headers, tokens, OTPs, or unredacted financial and identity payloads.

Service tokens are acquired and refreshed automatically. Shared multi-process deployments can inject Django Cache or Redis token storage and a distributed refresh lock.

For Django, define JIBIT = {...} in settings and use:

from jibit.django import get_jibit_client

client = get_jibit_client()

See the Django integration guide for cache and logging configuration.

Payment and refund submissions are never blindly retried. If a create or refund request times out, keep the SDK correlation ID and reconcile using the purchase or refund inquiry operation before deciding whether another business action is safe. See the Payment Gateway guide.

Transferor batch submissions and Cobank settlements are also never blindly retried. Use a unique batch_id or record_track_id, persist it before submission, and reconcile through the corresponding inquiry operation after any timeout or network failure. See the transfers and settlements guide.

Direct Debit response limitation

Five documented Direct Debit operations declare successful HTTP responses without a reliable response-body schema: mandate revoke, enable, disable, OTP dispatch, and the Blue Bank callback. The SDK treats them as status-only operations and keeps any response body optional. Consumers must not depend on undocumented body fields.

Documentation

• Architecture
• Configuration
• Authentication
• Payment Gateway
• Identicator and KYC
• Transfers and settlements
• Direct Debit
• Pulse SMS and MzaHub contracts
• Webhooks and callbacks
• Django integration
• Token storage
• Error handling
• Logging and audit events
• Retry and idempotency
• API support matrix
• Versioning and compatibility
• Production checklist
• Source provenance
• Security policy
• Contributing
• Changelog

License

Licensed under the Apache License 2.0. See LICENSE and NOTICE.