tirikchilik 0.2.0

An unofficial Python wrapper for Tirikchilik API.

Tirikchilik

Tirikchilik is an unofficial Python library for interacting with the Tirikchilik payment API. It supports Click and Uzum payment systems with typed response objects and full IDE autocompletion.

Note: This is an unofficial API wrapper and is not affiliated with or endorsed by Tirikchilik. Use at your own risk.

Table of Contents

1. Features
2. Installation
3. Quick Start
4. Payment Systems
5. API Reference
6. Response Objects
7. Error Handling
8. Dependencies
9. Contributing
10. Support
11. License

Features

• Multiple payment systems: Choose between Click and Uzum at payment creation time.
• Typed response objects: PaymentResponse and StatusResponse with named attributes — no more guessing dict keys.
• Custom return URL: Redirect users to your site after Click payment completion.
• Automatic project ID retrieval: Just provide your project name, the library resolves the ID.
• Robust error handling: Custom exceptions with code, message, and description attributes.
• Retry mechanism: Automatically retries on 5xx errors (3 retries with exponential backoff).
• Connection pooling: Up to 10 pooled HTTP connections.

Installation

pip install tirikchilik

Quick Start

from tirikchilik import Tirikchilik

client = Tirikchilik("MyProject")

# Create a payment (amount in tiyin: 1000000 = 10,000 UZS)
payment = client.create_payment(
    amount=1000000,
    donater="John Doe",
    notes="Donation for Project X",
)

print(payment.pay_id)            # "055ef757-3ca0-45b4-9f3e-a54d86c6ddac"
print(payment.checkout_url)      # "https://my.click.uz/services/pay?..."
print(payment.donate_amount)     # 950000
print(payment.commission_amount) # 50000
print(payment.total_amount)      # 1000000

# Check payment status
status = client.get_payment_status(payment.pay_id)
print(status.status)    # "Paid" or "Draft"
print(status.is_paid)   # True / False
print(status.is_draft)  # True / False

Payment Systems

Choose a payment provider with the payment_system parameter:

Click (default)

payment = client.create_payment(
    amount=1000000,
    donater="John Doe",
    notes="Donation",
    payment_system="click",
)
# payment.checkout_url → "https://my.click.uz/services/pay?..."

Uzum

payment = client.create_payment(
    amount=526316,
    donater="John Doe",
    notes="Donation",
    payment_system="uzum",
)
# payment.checkout_url → "https://www.apelsin.uz/open-service?..."

Custom return URL (Click only)

payment = client.create_payment(
    amount=500000,
    donater="John Doe",
    notes="Donation",
    payment_system="click",
    return_url="https://mysite.com/payment/success",
)
# The checkout_url will contain your return_url

API Reference

Tirikchilik(project_name: str)

Initialize a client. Automatically resolves the project name to a project ID.

• project_name — Your project name on tirikchilik.uz.

Raises UserNotFoundError if the project name is not found.

---

create_payment(amount, donater, notes, payment_system="click", return_url=None)

Create a new payment.

Parameter	Type	Required	Default	Description
amount	int	Yes	—	Amount in tiyin (1 UZS = 100 tiyin). E.g. 1000000 = 10,000 UZS.
donater	str	Yes	—	Name of the person making the payment.
notes	str	Yes	—	Notes or description for the payment.
payment_system	str	No	"click"	Payment provider: "click" or "uzum".
return_url	str	No	None	Redirect URL after payment (Click only).

Returns a PaymentResponse object.

---

get_payment_status(payment_id)

Get the status of a payment.

Parameter	Type	Required	Description
payment_id	str	Yes	The pay_id from PaymentResponse.

Returns a StatusResponse object.

Response Objects

PaymentResponse

Returned by create_payment().

Attribute	Type	Description
pay_id	str	Unique payment identifier (UUID).
checkout_url	str	URL to redirect the user to complete payment.
donate_amount	int	Net amount after commission (in tiyin).
commission_amount	int	Commission amount (in tiyin).
total_amount	int	Total amount charged (in tiyin).
raw	dict	The original API response dictionary.

StatusResponse

Returned by get_payment_status().

Attribute	Type	Description
status	str	Payment status string (e.g. "Paid", "Draft").
is_paid	bool	True if the payment has been completed.
is_draft	bool	True if the payment has not been paid yet.
raw	dict	The original API response dictionary.

Error Handling

from tirikchilik import Tirikchilik, PaymentNotFoundError, UserNotFoundError, PaymentError

client = Tirikchilik("MyProject")

try:
    payment = client.create_payment(
        amount=1000000,
        donater="John Doe",
        notes="Test",
    )
except PaymentNotFoundError as e:
    print(f"Payment not found: {e}")
except UserNotFoundError as e:
    print(f"User/project not found: {e}")
except PaymentError as e:
    print(f"Payment error: {e}")

Exception	Description
PaymentError	Base exception for all payment-related errors.
PaymentNotFoundError	Raised when the specified payment ID is not found.
UserNotFoundError	Raised when the project name cannot be resolved.

All exceptions have code, message, and description attributes.

Dependencies

• requests (~2.32.3)
• urllib3 (~2.2.3)

Automatically installed with pip install tirikchilik.

Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Support

If you like this project, please consider supporting it by making a donation:

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This is an unofficial API wrapper for Tirikchilik. It is not affiliated with, endorsed, or supported by Tirikchilik. Use this library at your own risk. The authors and contributors are not responsible for any misuse or damage caused by this software.