Metadata-Version: 2.4
Name: i-payment
Version: 0.1.1
Summary: Python client for the i-payment integration API
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: respx; extra == "dev"

# i-payment (Python)

Python client for the i-payment integration API. Supports both sync and async usage.

## Installation

```bash
pip install i-payment
```

## Quick start

```python
from i_payment import KaspiClient

client = KaspiClient(api_key="your-api-key")

# List cashiers attached to your project
cashiers = client.list_cashiers()

# Create an invoice payment
invoice = client.create_invoice(phone="77001234567", amount=5000.0, comment="Order #42")
print(invoice.operation_id)   # OperationId from Kaspi
print(invoice.status)         # "RemotePaymentCreated"

# Generate a QR code for in-person payment
qr = client.create_qr(amount=1500.0)
print(qr.qr_token)            # base64 QR image token
print(qr.qr_operation_id)     # poll status with this

# Poll QR status
status = client.qr_status(qr.qr_operation_id)
print(status.status)          # "WaitingForPayment" | "Paid" | "Expired"

# Refund
client.create_refund(qr_operation_id=12345678, return_amount=1500.0)

# Context manager (auto-closes HTTP session)
with KaspiClient(api_key="your-api-key") as c:
    history = c.invoice_history(max_result=50)
```

## Async

```python
import asyncio
from i_payment import AsyncKaspiClient

async def main():
    async with AsyncKaspiClient(api_key="your-api-key") as client:
        qr = await client.create_qr(amount=2000.0)
        print(qr.qr_token)

asyncio.run(main())
```

## Methods

| Method | Description |
|--------|-------------|
| `list_cashiers()` | Cashiers for the project |
| `client_info(phone)` | Kaspi customer lookup |
| `create_invoice(phone, amount, comment?)` | Invoice to customer's Kaspi app |
| `invoice_details(operation_id)` | Invoice status |
| `cancel_invoice(operation_id)` | Cancel pending invoice |
| `invoice_history(max_result?)` | Recent invoice history |
| `create_qr(amount, latitude?, longitude?)` | QR code payment |
| `qr_status(qr_operation_id)` | QR payment status |
| `operations_history(end_date, ...)` | Transaction history |
| `operation_details(operation_id)` | Single operation details |
| `create_refund(qr_operation_id, return_amount)` | Refund a QR payment |

## Errors

```python
from i_payment import ValidationError, AuthenticationError, RateLimitError

try:
    client.create_invoice(phone="bad", amount=-1)
except ValidationError as e:
    print(e.status_code, str(e))
except AuthenticationError:
    print("Check your API key")
```

## Options

```python
client = KaspiClient(
    api_key="your-api-key",
    base_url="https://api.ipay.kz",  # default
    timeout=30.0,                     # seconds
)
```
