paymentsoslib 0.0.2
A lightweight Python client for PaymentsOS Management and Reporting APIs.
Requires Python: >=3.10
Keywords: payments, paymentsos, reporting, api, client

# paymentsoslib

- [Description](#package-description)
- [Usage](#usage)
- [Installation](#installation)
- [Docstring](#docstring)
- [License](#license)

## Package Description

A lightweight Python client for **PaymentsOS** Management and **Reporting** APIs.

This library wraps:
- Session creation (Management API)
- Report Request creation/retrieval (Reporting API)
- Downloading and decompressing gzip CSV report files

> This client performs real HTTP calls to PaymentsOS. Provide valid credentials and account details. Avoid logging sensitive data.

## Usage

```python
# 0. Initialize PaymentsOS client
client = PaymentsOS(
    email="account.email@company.com",
    password="PASSWORD",
    account_id="ACCOUNT_ID",
    environment="live",
    api_version="1.1.0",
    timeout=30
)

# Example: Using date between 6 months ago and yesterday
from dateutil.relativedelta import relativedelta

date_from = datetime.now() - relativedelta(months=6)
date_from = date_from.replace(hour=0, minute=0, second=0, microsecond=0)

date_to = datetime.now() - relativedelta(days=1)
date_to = date_to.replace(hour=0, minute=0, second=0, microsecond=0)

# 1. Create report request
result = client.create_report_request(
    report_template_id="REPORT_TEMPLATE_ID",
    date_from = date_from,
    date_to = date_to,
    report_name="MY_REPORT_NAME",
    filter_timezone="America/Bogota",
    display_timezone="America/Bogota",
    timezone="-05:00",
    include_sftp_report_name_prefix=True
)

print("Report ID request created:", result["id"])

report_request_id = result["id"]

# Poll while status is 'in_progress'
poll_seconds = 30            # choose your interval
timeout_seconds = 600        # e.g., 10 minutes overall timeout
deadline = time.time() + timeout_seconds

while True:
    # 2. Retrieve current status
    response = client.retrieve_report_request(report_request_id=report_request_id)
    response.raise_for_status()

    status_body = response.json()
    status = (status_body.get("status") or "").strip()
    print(f"[{time.strftime('%Y-%m-%d %H:%M:%S')}] Report {report_request_id} status: {status}")

    if status != "in_progress":
        if status == "completed_successfully":
            print("Report completed successfully.")

            report_body = response.json()
            report_url = report_body.get("report_url")
            print(report_url)

            # 3. Download report
            output_path = r"C:\Admin\Output\File.csv"
            client.download_report_to_csv(report_url=report_url, output_path=output_path)
        elif status in {"Failed", "Error"}:
            print("Report failed. Decide whether to retry or alert.")
        else:
            print(f"Report finished with status '{status}'. Handle as needed.")
        break

    # Still in progress — check for timeout and sleep
    if time.time() >= deadline:
        raise TimeoutError(
            f"Report request '{report_request_id}' still 'in_progress' after {timeout_seconds}s."
        )

    time.sleep(poll_seconds)
```

## Installation

Install python and pip if you have not already.

Then run:

```bash
pip install pip --upgrade
```

For production:

```bash
pip install paymentsoslib
```

This will install the package and all of it's python dependencies.

If you want to install the project for development:

```bash
git clone https://github.com/aghuttun/paymentsoslib.git
cd paymentsoslib
pip install -e ".[dev]"
```

## Docstring

The script's docstrings follow the numpydoc style.

## License

BSD License (see license file)

[top](#paymentsoslib)