# FetcherPay Python SDK

Official Python SDK for the FetcherPay API — One API. Every Rail.

## Installation

```bash
pip install fetcherpay
```

## Quick Start

```python
from fetcherpay import FetcherPay

client = FetcherPay(
    api_key='fp_test_your_key',
    environment='sandbox'  # or 'production'
)

# Create a payment
payment = client.payments.create(
    amount=10000,  # $100.00 in cents
    currency='USD',
    source={'payment_method_id': 'pm_123'},
    destination={'payment_method_id': 'pm_456'},
    rail='auto'  # Auto-select optimal rail
)

print(payment['id'], payment['status'])
```

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `api_key` | str | required | Your FetcherPay API key |
| `environment` | str | 'sandbox' | 'sandbox' or 'production' |
| `base_url` | str | auto | Override base URL |
| `timeout` | int | 30 | Request timeout (seconds) |

## API Reference

### Payments

```python
# Create payment
payment = client.payments.create(
    amount=10000,
    source={'payment_method_id': 'pm_123'},
    destination={'payment_method_id': 'pm_456'},
    idempotency_key='unique-key'
)

# Retrieve payment
payment = client.payments.retrieve('pay_xxx')

# List payments
payments = client.payments.list(limit=10)

# Cancel payment
client.payments.cancel('pay_xxx', reason='Customer request')

# Refund payment
client.payments.refund('pay_xxx', amount=5000, reason='Partial refund')
```

### Ledger

```python
# List accounts
accounts = client.ledger.list_accounts()

# Get account balance
account = client.ledger.retrieve_account('la_xxx')
print(account['balance']['available'])

# List entries
entries = client.ledger.list_entries(account_id='la_xxx')
```

### Payment Methods

```python
# Create bank account
pm = client.payment_methods.create(
    type='bank_account',
    bank_account={
        'account_number': '000123456789',
        'routing_number': '011000015',
        'account_type': 'checking'
    }
)

# List payment methods
methods = client.payment_methods.list()
```

### Webhooks

```python
# Create webhook endpoint
webhook = client.webhooks.create(
    url='https://your-app.com/webhooks',
    events=['payment.settled', 'payment.failed']
)

# Verify webhook signature
is_valid = client.verify_webhook_signature(
    payload,
    signature,  # from X-FetcherPay-Signature header
    webhook['secret']
)
```

## Error Handling

```python
from fetcherpay import (
    FetcherPayError,
    AuthenticationError,
    ValidationError,
    NotFoundError
)

try:
    client.payments.create(...)
except AuthenticationError:
    print('Invalid API key')
except ValidationError as e:
    print(f'Validation failed: {e.param}')
except FetcherPayError as e:
    print(f'API error: {e.type} ({e.status_code})')
```

## Webhook Verification

```python
import json

# In your webhook handler
def handle_webhook(request):
    payload = request.body
    signature = request.headers.get('X-FetcherPay-Signature')
    secret = 'whsec_your_webhook_secret'
    
    if client.verify_webhook_signature(payload, signature, secret):
        event = json.loads(payload)
        if event['type'] == 'payment.settled':
            handle_payment_settled(event['data'])
        return 'OK', 200
    else:
        return 'Invalid signature', 401
```

## License

MIT