fetcherpay-python/README.md

FetcherPay Python SDK

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

Installation

pip install fetcherpay

Quick Start

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

# 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

# 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

# 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

# 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

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

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