Metadata-Version: 2.4
Name: athm
Version: 0.2.0b0
Summary: A modern Python library for the ATH Móvil payment API
Project-URL: Homepage, https://github.com/django-athm/athm-python
Project-URL: Documentation, https://athm-python.readthedocs.io
Project-URL: Repository, https://github.com/django-athm/athm-python
Project-URL: Issues, https://github.com/django-athm/athm-python/issues
Project-URL: Changelog, https://github.com/django-athm/athm-python/blob/main/CHANGELOG.md
Author-email: Raúl Negrón-Otero <raul.esteban.negron@gmail.com>
Maintainer-email: Raúl Negrón-Otero <raul.esteban.negron@gmail.com>
License: MIT
License-File: LICENSE
Keywords: api,ath,athmovil,ecommerce,payment,payments,puerto-rico
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Pydantic
Classifier: Framework :: Pydantic :: 2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1.0.0,>=0.24.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: typing-extensions<5.0.0,>=4.0.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: commitizen>=3.30.0; extra == 'dev'
Requires-Dist: git-cliff>=2.6.0; extra == 'dev'
Requires-Dist: mkdocs>=1.6.0; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pymdown-extensions>=10.0; extra == 'dev'
Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# ATH Móvil Unofficial Library

[![PyPI version](https://badge.fury.io/py/athm.svg)](https://badge.fury.io/py/athm)
[![Python Versions](https://img.shields.io/pypi/pyversions/athm.svg)](https://pypi.org/project/athm/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/yourusername/athm-python/actions/workflows/test.yml/badge.svg)](https://github.com/yourusername/athm-python/actions/workflows/test.yml)

A modern, type-safe Python library for the ATH Móvil payment platform.

> **Note**: This is an unofficial, third-party library and is not affiliated with, endorsed by, or supported by ATH Móvil or EVERTEC. For official API documentation, see the [ATH Móvil Payment Button API](https://github.com/evertec/ATHM-Payment-Button-API).

> Developed with AI assistance using Claude Code (claude.ai)

## Features

- Full ATH Móvil Payment Button API support
- Simple synchronous client
- Strict type safety with mypy
- Pydantic data validation
- Automatic retries with exponential backoff
- Comprehensive error handling
- High test coverage

## Installation

```bash
pip install athm
```

Or with uv:

```bash
uv add athm
```

## Quick Start

```python
from athm import ATHMovilClient

client = ATHMovilClient(public_token="your_public_token")

payment = client.create_payment(
    total="100.00",
    phone_number="7875551234",  # Customer's phone number with ATH Móvil account
    metadata1="Order #123",
    items=[
        {
            "name": "Product Name",
            "description": "Product Description",
            "quantity": "1",
            "price": "100.00",
        }
    ],
)

confirmed = client.wait_for_confirmation(payment.ecommerce_id)

if confirmed:
    result = client.authorize_payment(payment.ecommerce_id)
    print(f"Payment completed: {result.data.reference_number}")
```

## Configuration

Get your credentials from your ATH Business account settings.

```python
client = ATHMovilClient(
    public_token=os.getenv("ATHM_PUBLIC_TOKEN"),
    private_token=os.getenv("ATHM_PRIVATE_TOKEN"),  # Required for refunds
)
```

## Supported Operations

- Create payments
- Check payment status
- Authorize confirmed payments
- Update phone numbers
- Cancel payments
- Process full and partial refunds

## Error Handling

```python
from athm.exceptions import ValidationError, ATHMovilError

try:
    payment = client.create_payment(
        total="0.50",  # Below minimum - will raise ValidationError
        phone_number="7875551234",  # Customer's phone number with ATH Móvil account
        items=[{"name": "Test", "description": "Test", "quantity": "1", "price": "0.50"}],
    )
except ValidationError as e:
    print(f"Invalid data: {e}")
except ATHMovilError as e:
    print(f"Error: {e}")
```

## Context Manager

```python
with ATHMovilClient(public_token="token") as client:
    payment = client.create_payment(
        total="100.00",
        phone_number="7875551234",  # Customer's phone number with ATH Móvil account
        items=[{"name": "Test", "description": "Test", "quantity": "1", "price": "100.00"}],
    )
    # Client is automatically closed when exiting the context
```

## Documentation

- [Full Documentation](https://athm-python.readthedocs.io)
- [API Reference](https://athm-python.readthedocs.io/en/latest/api/)

## Development

```bash
git clone https://github.com/yourusername/athm-python.git
cd athm-python
uv sync --all-extras --dev
uv run pytest
```

### Code Quality

```bash
uv run ruff format athm tests
uv run ruff check athm tests --fix
uv run mypy athm
```

## Requirements

- Python 3.10+
- httpx
- pydantic

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

MIT License - see [LICENSE](LICENSE) for details.
