paymentsoslib

• Description
• Usage
• Installation
• Docstring
• 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

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

pip install pip --upgrade

For production:

pip install paymentsoslib

This will install the package and all of it's python dependencies.

If you want to install the project for development:

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