Zarinpal Python SDK

A modern, type-safe Python SDK for Zarinpal Payment Gateway with both synchronous and asynchronous support.

Features

• ✅ Sync and async client support
• ✅ Type hints and full IDE autocomplete
• ✅ Comprehensive error handling
• ✅ Support for all Zarinpal API endpoints
• ✅ Sandbox environment for testing
• ✅ Custom StartPay endpoint configuration
• ✅ Wage splitting for shared settlements
• ✅ Fee calculation utilities

Installation

pip install irgateway

Quick Start

Synchronous Usage

from irgateway.zarinpal import ZarinpalClient
from irgateway.zarinpal.enums import Environment, Currency

# Initialize client
client = ZarinpalClient(
    merchant_id="YOUR-MERCHANT-ID",
    environment=Environment.SANDBOX  # Use PRODUCTION for live
)

# Create payment request
payment = client.request(
    amount=10000,
    callback_url="https://yoursite.com/callback",
    description="خرید محصول"
)

print(f"Payment URL: {payment.payment_url}")

# Verify payment after callback
verification = client.verify(
    authority="A00000000000000000000000000123456789",
    amount=10000
)

print(f"Reference ID: {verification.ref_id}")

Asynchronous Usage

from irgateway.zarinpal import ZarinpalClient
from irgateway.zarinpal.enums import Environment, Currency

async def process_payment():
    async with AsyncZarinpalClient(
        merchant_id="YOUR-MERCHANT-ID",
        environment=Environment.SANDBOX
    ) as client:
        payment = await client.request(
            amount=10000,
            callback_url="https://yoursite.com/callback",
            description="خرید محصول"
        )
        return payment.payment_url

# In your async function
url = await process_payment()

API Methods

Advanced Features

Payment Metadata

from irgateway.types import PaymentMetadata

metadata = PaymentMetadata(
    mobile="09123456789",
    email="user@example.com"
)

payment = client.request(
    amount=10000,
    callback_url="https://yoursite.com/callback",
    description="خرید محصول",
    metadata=metadata
)

Wage Splitting

from irgateway.zarinpal.types import Wage

wages = [
    Wage(iban="IR123456789012345678901234", amount=5000),
    Wage(iban="IR987654321098765432109876", amount=3000)
]

payment = client.request(
    amount=10000,
    callback_url="https://yoursite.com/callback",
    description="خرید مشترک",
    wages=wages
)

Configuration

from irgateway.zarinpal import ZarinpalClient, ZarinpalConfig

config = ZarinpalConfig(
    timeout=30,  # Request timeout in seconds
    startpay_endpoint="https://custom-gateway.com/"  # Optional custom gateway
)

client = ZarinpalClient(
    merchant_id="YOUR-MERCHANT-ID",
    config=config
)

Error Handling

from irgateway.zarinpal.errors import ZarinpalException, InvalidMerchantError

try:
    payment = client.request(...)
except InvalidMerchantError:
    print("Merchant ID is invalid")
except ZarinpalException as e:
    print(f"Error {e.code}: {e.message}")

Requirements

• Python 3.7+
• requests (for sync client)
• aiohttp (for async client)

Development

# Clone repository
git clone https://github.com/javad2nd/irgateway.git
cd irgateway

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.