Metadata-Version: 2.4
Name: wipop_client
Version: 0.0.1
Summary: Wipöp API Client
License: None
Author: Harold Castillo
Requires-Python: >=3.12,<4.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: httpx (>=0.25.0,<0.26.0)
Requires-Dist: pydantic (>=2.0.0,<3.0.0)
Description-Content-Type: text/markdown

# Wipop Python Client

[![PyPI version](https://badge.fury.io/py/wipop-client.svg)](https://badge.fury.io/py/wipop-client)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

A modern Python client library for the Wipop payment processing API with full type safety and comprehensive error handling.

## Features

- **Card Charge Operations**
  - Payment link generation
  - Refunds
  - Pre-authorization creation
  - Pre-authorization confirmation
  - Pre-authorization reversal
  - Token generation
  - One-click charges
  - Recurring charges
- **Bizum Charge Operations**
  - Payment link creation
  - Refunds
- **Checkout Operations**
  - Payment link generation
  - Payment button

## Installation

```bash
# pip
pip install wipop-client

# poetry
poetry add wipop-client

# pipenv
pipenv install wipop-client
```

## Before Getting Started
- Have completed the identification process during the Wipöp payment gateway contracting.
- Access the control panel in test mode (sandbox) from your account.
- Clearly define which method you will use to perform the integration in your system:

### Required credentials:
- Merchant ID
- Secret API Key
- Terminal ID (default is 1 in sandbox)

## Quick Start

```python
from wipop_client import (
    WipopClient,
    WipopClientConfiguration,
    WipopEnvironment,
    CreateChargeParams,
    ChargeMethod,
    Currency,
    OriginChannel,
    ProductType
)

# Initialize client
config = WipopClientConfiguration(
    location=WipopEnvironment.SANDBOX,
    merchant_id='your-merchant-id',
    secret_key='your-secret-key'
)
client = WipopClient(config)

# Create a charge
charge = client.charge_operation().create(
    CreateChargeParams(
        method=ChargeMethod.CARD,
        origin_channel=OriginChannel.API,
        amount=100.00,
        currency=Currency.EUR,
        description='Payment for order #123',
        order_id='1234a1B2c3D4',
        product_type=ProductType.PAYMENT_LINK,
        terminal={'id': '1'}
    )
)
```

## API Reference

### Configuration

#### Basic Configuration

```python
config = WipopClientConfiguration(
    location=WipopEnvironment.SANDBOX,  # WipopEnvironment.PRODUCTION for live
    merchant_id='your-merchant-id',
    secret_key='your-secret-key'
)
```

#### Advanced Configuration

```python
from wipop_client import WipopClientHttpConfiguration

http_config = WipopClientHttpConfiguration(
    timeout=30  # request timeout (seconds)
)

config = WipopClientConfiguration(
    location=WipopEnvironment.SANDBOX,
    merchant_id='merchant-id',
    secret_key='secret-key',
    http_configuration=http_config
)
```

#### Custom Environment

```python
config = WipopClientConfiguration(
    location='https://custom-api.wipop.es',
    merchant_id='merchant-id',
    secret_key='secret-key'
)
```

### Charge Operations

#### Create Card Charge

```python
card_charge = client.charge_operation().create(
    CreateChargeParams(
        method=ChargeMethod.CARD,
        origin_channel=OriginChannel.API,
        product_type=ProductType.PAYMENT_LINK,
        amount=31.00,
        currency=Currency.EUR,
        description='Test redirection payment link',
        order_id='1234a1B2c3D4',
        redirect_url='https://example.com',
        send_email=True,
        language='es-ES',
        terminal={'id': '1'}
    )
)
```

#### Create Bizum Charge

```python
bizum_charge = client.charge_operation().create(
    CreateChargeParams(
        method=ChargeMethod.BIZUM,
        origin_channel=OriginChannel.API,
        product_type=ProductType.PAYMENT_LINK,
        amount=20.00,
        currency=Currency.EUR,
        description='Checkout charge link bizum',
        order_id='1234a1B2c3D4',
        redirect_url='https://example.com',
        send_email=True,
        language='es-ES',
        terminal={'id': '1'}
    )
)
```

#### Create Customer Charge

```python
customer_charge = client.charge_operation().create_customer_charge(
    'customer-id',
    CreateChargeParams(
        method=ChargeMethod.CARD,
        origin_channel=OriginChannel.API,
        amount=75.00,
        currency=Currency.EUR,
        description='Customer payment',
        order_id='1234a1B2c3D4',
        product_type=ProductType.PAYMENT_LINK,
        terminal={'id': '1'}
    )
)
```

#### Confirm Charge

```python
from wipop_client import ConfirmChargeParams

confirmed_charge = client.charge_operation().confirm(
    't00000000000000000000',
    ConfirmChargeParams(token_id='k000000000000000000')
)
```

#### Refund Charge

```python
from wipop_client import RefundParams

refunded_charge = client.charge_operation().refund(
    't00000000000000000000',
    RefundParams(amount=25.00)
)
```

#### Reverse Charge

```python
from wipop_client import ReversalParams

reversed_charge = client.charge_operation().reversal(
    't00000000000000000000',
    ReversalParams(description='Transaction reversal')
)
```

#### Capture Charge

```python
from wipop_client import CaptureParams

captured_charge = client.charge_operation().capture(
    't00000000000000000000',
    CaptureParams(amount=100.00)
)
```

### Checkout Operations

#### Create Checkout

```python
from wipop_client import CheckoutParams

checkout = client.checkout_operation().create_checkout(
    CheckoutParams(
        amount=10.00,
        currency=Currency.EUR,
        description='Checkout test payment gateway',
        redirect_url='https://www.example.com',
        order_id='1234a1B2c3D4',
        origin_channel=OriginChannel.API,
        product_type=ProductType.PAYMENT_GATEWAY,
        expiration_date='2025-10-29 12:50',
        language='es-ES',
        terminal={'id': '1'}
    )
)

print(f'Checkout URL: {checkout.checkout_url}')
```

#### Create Customer Checkout

```python
customer_checkout = client.checkout_operation().create_customer_checkout(
    'customer-id',
    CheckoutParams(
        origin_channel=OriginChannel.API,
        amount=100.00,
        currency=Currency.EUR,
        description='Customer checkout',
        order_id='1234a1B2c3D4',
        product_type=ProductType.PAYMENT_LINK
    )
)
```

## Language Support

The library includes support for internationalization with the `Language` class:

```python
from wipop_client import Language

# Create language instances
spanish = Language('es', 'ES')  # Spanish (Spain)
english = Language('en', 'US')  # English (United States)
french = Language('fr', 'FR')   # French (France)

# Use in checkout parameters
checkout = CheckoutParams(
    origin_channel=OriginChannel.API,
    amount=100.00,
    description='Product purchase',
    order_id='1234a1B2c3D4',
    language=spanish,
    product_type=ProductType.PAYMENT_LINK
)

# Use in charge parameters
charge = CreateChargeParams(
    method=ChargeMethod.CARD,
    origin_channel=OriginChannel.API,
    amount=100.00,
    order_id='1234a1B2c3D4',
    language=english,
    product_type=ProductType.PAYMENT_LINK
)
```

## Supported Payment Methods

- **CARD** - Credit and debit card payments
- **BIZUM** - Spanish mobile payment system

## Supported Currencies

- **EUR** - Euro
- Additional currencies as supported by the Wipop API

## Transaction Status

The client uses the `TransactionStatus` enum for type-safe status handling:

- `CHARGE_PENDING` - Charge is pending processing
- `COMPLETED` - Transaction completed successfully
- `ERROR` - Transaction failed with error
- `FAILED` - Transaction failed
- `IN_PROGRESS` - Transaction is being processed

## Error Handling

```python
from wipop_client import WipopClientError

try:
    charge = client.charge_operation().create(charge_params)
except WipopClientError as error:
    print(f'Wipop API Error: {error.message}')
    
    if error.response_code:
        print(f'Error Code: {error.response_code.code}')
        print(f'Error Message: {error.response_code.message}')
        print(f'Error Level: {error.response_code.level}')
except Exception as error:
    print(f'Unexpected error: {error}')
```

## Development

### Prerequisites

- Python 3.8+
- Poetry (recommended) or pip

### Scripts

```bash
# Install dependencies
poetry install

# Run tests
poetry run pytest

# Run tests with coverage
poetry run pytest --cov=wipop_client

# Run tests in watch mode
poetry run ptw

# Format code
poetry run black wipop_client tests

# Check formatting
poetry run black --check wipop_client tests

# Type checking
poetry run mypy wipop_client

# Linting
poetry run flake8 wipop_client tests
```

### Testing

The project uses pytest for testing with comprehensive test coverage:

```bash
# Run all tests
poetry run pytest

# Run specific test module
poetry run pytest tests/test_charge.py

# Generate coverage report
poetry run pytest --cov=wipop_client --cov-report=html
```

## Support

For support and questions, please contact the support team or [create an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/learning-about-issues/quickstart) in the project repository.
