tirikchilik 0.1.0

An unofficial Python wrapper for Tirikchilik API.

Tirikchilik

Tirikchilik is an unofficial Python library for interacting with the Tirikchilik payment API. It provides a simple and efficient way to create payments via Click, check payment statuses, and handle various payment-related operations.

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. API Reference
5. Error Handling
6. Dependencies
7. Contributing
8. Support
9. License

Features

• Easy-to-use interface: Simplifies the payment process with minimal configuration.
• Click payment system: Payments are processed through Click with automatic checkout URL generation.
• Custom return URL: Optionally specify where to redirect users after payment completion.
• Automatic project ID retrieval: No need for manual project ID entry — just provide your project name.
• Robust error handling: Custom exceptions for different failure scenarios.
• Retry mechanism: Automatically retries failed requests (3 retries with exponential backoff on 5xx errors).
• Connection pooling: Efficient HTTP connection management with up to 10 pooled connections.
• Type hinting: Full type annotations for better IDE support.

Installation

pip install tirikchilik

Quick Start

from tirikchilik import Tirikchilik

# Initialize the client with your project name
client = Tirikchilik("MyProject")

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

# Get payment ID and checkout URL
payment_id = payment_response['data']['payId']
checkout_url = payment_response['data']['checkoutUrl']

print(f"Payment ID: {payment_id}")
print(f"Checkout URL: {checkout_url}")

# Check payment status
status_response = client.get_payment_status(payment_id)
print(f"Payment status: {status_response['data']}")

With custom return URL

You can specify a return_url to redirect users back to your site after payment:

payment_response = client.create_payment(
    amount=500000,
    donater="John Doe",
    notes="Donation",
    return_url="https://mysite.com/payment/success"
)

# The checkoutUrl will redirect to your return_url after payment
print(payment_response['data']['checkoutUrl'])

API Reference

Tirikchilik(project_name: str)

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

• project_name — The name of your project on tirikchilik.uz.

Raises UserNotFoundError if the project name is not found.

---

create_payment(amount, donater, notes, return_url=None)

Create a new payment via Click.

Parameter	Type	Required	Description
amount	int	Yes	Payment 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.
return_url	str	No	URL to redirect the user to after payment. If not provided, the default Click return URL is used.

Returns a dictionary:

{
    'data': {
        'payId': '055ef757-3ca0-45b4-9f3e-a54d86c6ddac',
        'checkoutUrl': 'https://my.click.uz/services/pay?service_id=...&amount=10000&...',
        'donateAmount': 950000,
        'commissionAmount': 50000,
        'totalAmount': 1000000
    },
    'success': True,
    'error': None
}

Field	Description
payId	Unique payment identifier (UUID).
checkoutUrl	URL to redirect the user to complete payment on Click.
donateAmount	Net amount after commission (in tiyin).
commissionAmount	Commission amount (in tiyin).
totalAmount	Total amount charged (in tiyin).

---

get_payment_status(payment_id)

Get the status of a payment.

Parameter	Type	Required	Description
payment_id	str	Yes	The payId returned from create_payment.

Returns a dictionary:

# Paid
{'data': 'Paid', 'success': True, 'error': None}

# Not yet paid
{'data': 'Draft', 'success': True, 'error': None}

Error Handling

Tirikchilik provides custom exceptions for different error scenarios:

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"General 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.