tirikchilik 0.1.0
An unofficial Python wrapper for Tirikchilik API.
License: MIT
Requires Python: >=3.9


# Tirikchilik

[![PyPI version](https://img.shields.io/pypi/v/tirikchilik)](https://pypi.org/project/tirikchilik/)
[![Python Versions](https://img.shields.io/pypi/pyversions/tirikchilik.svg)](https://pypi.org/project/tirikchilik/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![Downloads](https://img.shields.io/pypi/dm/tirikchilik)
<p align="center">
  <a href="https://tirikchilik.uz/araltech">
    <img src="https://camo.githubusercontent.com/ed28339e5a5786534715b1c0c885271437761fc91af84d5dc5bbc2c71e307a02/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f546972696b6368696c696b2d6666646430303f7374796c653d666f722d7468652d6261646765" alt="Donate with Tirikchilik">
  </a>
</p>

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](#features)
2. [Installation](#installation)
3. [Quick Start](#quick-start)
4. [API Reference](#api-reference)
5. [Error Handling](#error-handling)
6. [Dependencies](#dependencies)
7. [Contributing](#contributing)
8. [Support](#support)
9. [License](#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

```bash
pip install tirikchilik
```

## Quick Start

```python
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:

```python
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:

```python
{
    '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:

```python
# 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:

```python
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](https://pypi.org/project/requests/) (~2.32.3)
- [urllib3](https://pypi.org/project/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:
<p align="center">
  <a href="https://tirikchilik.uz/araltech">
    <img src="https://camo.githubusercontent.com/ed28339e5a5786534715b1c0c885271437761fc91af84d5dc5bbc2c71e307a02/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f546972696b6368696c696b2d6666646430303f7374796c653d666f722d7468652d6261646765" alt="Donate with Tirikchilik">
  </a>
</p>

## License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/Diyarbekoralbaev/tirikchilik/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.