unepay-sdk 1.0.1

unepay sdk for python

Unepay Python SDK

Python SDK for working with Unepay API. Easy way to create payments, check their status and manage them through Python.

Installation

pip install unepay-sdk

Or from source:

pip install .

Quick Start

Simple payment creation example

from unepay_lib import UnepayClient

# Initialize client
client = UnepayClient(
    api_key="unepay_your_api_key_here",
    base_url="https://unepay.lol"
)

# Create payment
payment = client.create_payment(
    payment_id="order_12345",      # Your internal order ID
    amount=1500.0,                  # Amount in rubles
    expires_in=600,                 # Lifetime in seconds (10 minutes)
    comment="Payment for order #12345"  # Comment (optional)
)

print(f"Payment URL: {payment.payment_url}")
print(f"Payment ID: {payment.id}")
print(f"External ID: {payment.external_id}")  # Your order ID

# Check payment status
status = client.get_payment_status(payment.id)
print(f"Status: {status.status}")
print(f"Is expired: {status.is_expired}")

# Get list of active payments
active_payments = client.list_active_payments()
for p in active_payments:
    print(f"{p.external_id}: {p.amount} RUB - {p.status}")

Full example with error handling

from unepay_lib import UnepayClient, UnepayAuthError, UnepayAPIError

client = UnepayClient(
    api_key="your_api_key",
    base_url="https://unepay.lol"
)

try:
    # Create payment
    payment = client.create_payment(
        payment_id="order_12345",
        amount=1500.0,
        expires_in=600,
        comment="Payment for order"
    )
    
    print(f"✓ Payment created!")
    print(f"  URL: {payment.payment_url}")
    print(f"  ID: {payment.id}")
    
    # Track status
    import time
    while True:
        status = client.get_payment_status(payment.id)
        if status.status == "paid":
            print("✓ Payment completed!")
            break
        elif status.is_expired:
            print("⚠ Payment expired")
            break
        print(f"Status: {status.status}, waiting...")
        time.sleep(5)
        
except UnepayAuthError as e:
    print(f"Authentication error: {e}")
except UnepayAPIError as e:
    print(f"API error: {e}")

API Documentation

Client initialization

client = UnepayClient(
    api_key: str,
    base_url: str,
    timeout: int = 30
)

Parameters:

• api_key (required) - Your merchant API key
• base_url (required) - Base URL of the API (e.g., "https://unepay.lol" or "http://localhost:3000")
• timeout (optional) - Request timeout in seconds

Create payment

payment = client.create_payment(
    payment_id: str,
    amount: float,
    expires_in: int,
    comment: Optional[str] = None
) -> Payment

Parameters:

• payment_id - Unique payment ID (your internal identifier)
• amount - Payment amount in rubles
• expires_in - Payment lifetime in seconds
• comment - Payment comment (optional)

Returns: Payment object with created payment data

Example:

payment = client.create_payment(
    payment_id="order_123",
    amount=2500.50,
    expires_in=1800,  # 30 minutes
    comment="Payment for product"
)

Get payment status

payment = client.get_payment_status(payment_id: str) -> Payment

Parameters:

• payment_id - Payment ID (public_id, returned when created)

Returns: Payment object with current status

Example:

payment = client.get_payment_status("n5AvkX5BhasxnL00EnhIVA9kZeXKquTb")
print(f"Status: {payment.status}")
print(f"Amount: {payment.amount} RUB")
print(f"Is expired: {payment.is_expired}")

Get full payment information

payment = client.get_payment(payment_id: str) -> Payment

Parameters:

• payment_id - Payment ID (public_id)

Returns: Payment object with full information

List active payments

payments = client.list_active_payments() -> List[Payment]

Returns: List of Payment objects with all active payments for the merchant

Example:

payments = client.list_active_payments()
for payment in payments:
    print(f"ID: {payment.external_id}")
    print(f"Amount: {payment.amount} RUB")
    print(f"Status: {payment.status}")
    print(f"URL: {payment.payment_url}")
    print("---")

Payment Model

The Payment object contains the following information:

@dataclass
class Payment:
    id: str                    # Public ID (used in URL)
    external_id: str           # Your internal ID
    amount: float              # Payment amount
    comment: str               # Comment
    status: str                # Status: pending, paid, expired, cancelled
    expires_at: int            # Expiration timestamp (milliseconds)
    created_at: int            # Creation timestamp (milliseconds)
    paid_at: int               # Payment timestamp (milliseconds)
    payment_url: str           # Payment page URL
    is_expired: bool           # Expiration flag

Useful properties:

• expires_at_datetime - expires_at as datetime object
• created_at_datetime - created_at as datetime object
• paid_at_datetime - paid_at as datetime object

Example:

payment = client.get_payment_status(payment_id)
if payment.expires_at_datetime:
    print(f"Expires at: {payment.expires_at_datetime.strftime('%Y-%m-%d %H:%M:%S')}")

Error Handling

The library uses the following exceptions:

• UnepayException - Base exception
• UnepayAPIError - General API error
• UnepayAuthError - Authentication error (invalid API key)
• UnepayNotFoundError - Resource not found (404)
• UnepayValidationError - Data validation error (400)

Error handling example:

from unepay_lib import UnepayClient, UnepayAuthError, UnepayAPIError

try:
    client = UnepayClient(api_key="invalid_key")
    payment = client.create_payment(...)
except UnepayAuthError as e:
    print(f"Authentication error: {e}")
except UnepayAPIError as e:
    print(f"API error: {e}")
    print(f"Status code: {e.status_code}")

Usage Examples

Create and track payment

from unepay_lib import UnepayClient
import time

client = UnepayClient(api_key="your_api_key", base_url="https://unepay.lol")

# Create payment
payment = client.create_payment(
    payment_id="order_123",
    amount=1000.0,
    expires_in=600,
    comment="Payment for order"
)

print(f"Payment created: {payment.payment_url}")

# Track status
while True:
    status = client.get_payment_status(payment.id)
    
    if status.status == "paid":
        print("Payment completed!")
        break
    elif status.status == "expired" or status.is_expired:
        print("Payment expired")
        break
    
    print(f"Status: {status.status}, waiting...")
    time.sleep(5)  # Check every 5 seconds

Get payment statistics

from unepay_lib import UnepayClient
from collections import Counter

client = UnepayClient(api_key="your_api_key", base_url="https://unepay.lol")
payments = client.list_active_payments()

# Statistics by status
statuses = Counter(p.status for p in payments)
print("Payment statuses:", dict(statuses))

# Total amount of active payments
total_amount = sum(p.amount for p in payments if p.status == "pending")
print(f"Total pending amount: {total_amount} RUB")

# Number of paid payments
paid_count = sum(1 for p in payments if p.status == "paid")
print(f"Paid payments: {paid_count}")

License

MIT

Support

If you have questions or issues, create an issue in the project repository.