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.
Developed with AI assistance using Claude Code (claude.ai)
- Full ATH Móvil Payment Button API support
- Webhook support for real-time transaction notifications
- Simple synchronous client
- Strict type safety with mypy
- Pydantic data validation
- Automatic retries with exponential backoff
- Comprehensive error handling
pip install athmOr with uv:
uv add athmfromathmimportATHMovilClient# Note: private token is only required for processing refundsclient=ATHMovilClient(public_token="your_public_token", private_token="your_private_token")
payment=client.create_payment(
total="5.00",
phone_number="7875551234",
metadata1="Order #123",
items=[
{
"name": "Product Name",
"description": "Product Description",
"quantity": "1",
"price": "5.00",
}
],
)
# Wait for customer confirmationclient.wait_for_confirmation(payment.data.ecommerce_id)
# Authorize paymentpayment_result=client.authorize_payment(payment.data.ecommerce_id)
print(f"Payment completed: {payment_result.data.reference_number}")
# Refund the payment (requires a client initialized with private token)refund_result=client.refund_payment(
reference_number=payment_result.data.reference_number,
amount="5.00",
)Get your credentials from your ATH Business account settings.
client=ATHMovilClient(
public_token=os.getenv("ATHM_PUBLIC_TOKEN"),
private_token=os.getenv("ATHM_PRIVATE_TOKEN"), # Required for refunds
)- Create payments
- Check payment status
- Authorize confirmed payments
- Cancel payments
- Process full and partial refunds
- Update phone numbers
- Subscribe to webhook notifications
- Parse and validate webhook payloads
fromathm.exceptionsimportValidationError, ATHMovilErrortry:
payment=client.create_payment(
total="5.00",
phone_number="7875551234", # Customer's phone number with ATH Móvil accountitems=[{"name": "Test", "description": "Test", "quantity": "1", "price": "5.00"}],
)
exceptValidationErrorase:
print(f"Invalid data: {e}")
exceptATHMovilErrorase:
print(f"Error: {e}")withATHMovilClient(public_token="token") asclient:
payment=client.create_payment(
total="5.00",
phone_number="7875551234", # Customer's phone number with ATH Móvil accountitems=[{"name": "Test", "description": "Test", "quantity": "1", "price": "5.00"}],
)
# Client is automatically closed when exiting the contextSubscribe to real-time transaction notifications:
# Subscribe to webhooks (requires private token)client=ATHMovilClient(
public_token="your_public_token",
private_token="your_private_token",
)
client.subscribe_webhook(
listener_url="https://yoursite.com/webhook",
payment_received_event=True,
refund_sent_event=True,
ecommerce_payment_received_event=True,
ecommerce_payment_cancelled_event=True,
ecommerce_payment_expired_event=True,
)Parse incoming webhook payloads in your endpoint:
fromathm.webhooksimportparse_webhook, WebhookEventType, WebhookStatus@app.post("/webhook")asyncdefhandle_webhook(request: Request):
payload=awaitrequest.json()
event=parse_webhook(payload)
ifevent.status==WebhookStatus.COMPLETED:
ifevent.transaction_type==WebhookEventType.PAYMENT:
# Standard payment completedprint(f"Payment received: {event.reference_number} for ${event.total}")
elifevent.transaction_type==WebhookEventType.ECOMMERCE:
# eCommerce payment completedprint(f"Order {event.ecommerce_id} completed: ${event.total}")
elifevent.transaction_type==WebhookEventType.REFUND:
# Refund processedprint(f"Refund sent: {event.reference_number}")
elifevent.status==WebhookStatus.CANCELLED:
print(f"Transaction cancelled: {event.ecommerce_id}")
elifevent.status==WebhookStatus.EXPIRED:
print(f"Transaction expired: {event.ecommerce_id}")
return {"status": "ok"}git clone https://github.com/django-athm/athm-python.git
cd athm-python
uv sync --all-extras --dev
uv run pytestuv run ruff format
uv run ruff check
uv run mypy athm- Python 3.10+
- httpx
- pydantic
Contributions are welcome! Please see CONTRIBUTING.md for details.
MIT License - see LICENSE for details.