Paddle

You are integrating Paddle Billing as a Merchant of Record (MoR) into a [Django / Next.js / etc.] application.

## Key Concept: Paddle is the Merchant of Record
Paddle is NOT just a payment processor — it is the legal seller. Paddle handles tax collection, compliance, invoicing, chargebacks, and refunds on your behalf. You receive net payouts after Paddle deducts fees and taxes. This means:
- You do NOT need to collect or remit sales tax/VAT/GST
- Paddle issues invoices to your customers (not you)
- Amounts in webhooks may differ from what you see in payouts (taxes are deducted)
- Customer support for billing issues goes through Paddle

## Setup
1. Create a Paddle account at paddle.com and complete business verification (takes 1-3 days)
2. Get your API credentials from Developer Tools in the Paddle dashboard:
   - `PADDLE_API_KEY` (server-side API key)
   - `PADDLE_WEBHOOK_SECRET` (per notification destination)
   - `PADDLE_CLIENT_TOKEN` (client-side token for Paddle.js)
   - `PADDLE_ENVIRONMENT` ('sandbox' or 'production')
3. Store all credentials in environment variables — NEVER hardcode them
4. Use the sandbox environment for development: sandbox-api.paddle.com

## Recommended Integration: Overlay Checkout
The fastest way to integrate — add Paddle.js and turn any element into a checkout trigger:

```html
<!-- Add Paddle.js to your page -->
<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
<script>
  Paddle.Initialize({
    token: 'YOUR_CLIENT_TOKEN',
    environment: 'sandbox', // Remove for production
  });
</script>

<!-- Open checkout on click -->
<a href="#" class="paddle_button"
   data-items='[{"priceId": "pri_abc123", "quantity": 1}]'
   data-custom-data='{"user_id": "your_internal_id"}'>
  Buy Now
</a>
```

Or open programmatically:
```javascript
Paddle.Checkout.open({
  items: [{ priceId: 'pri_abc123', quantity: 1 }],
  customData: { userId: 'your_internal_id' },
  settings: {
    successUrl: 'https://yourdomain.com/success',
  }
});
```

## Server-Side: Create Products and Prices
Set up your product catalog via the API or dashboard:

```python
import requests

headers = {
    'Authorization': f'Bearer {PADDLE_API_KEY}',
    'Content-Type': 'application/json',
}

# Create a product
product = requests.post(
    f'{PADDLE_API_URL}/products',
    headers=headers,
    json={
        'name': 'Pro Plan',
        'tax_category': 'standard',  # Paddle handles tax based on this
    }
).json()

# Create a recurring price
price = requests.post(
    f'{PADDLE_API_URL}/prices',
    headers=headers,
    json={
        'product_id': product['data']['id'],
        'description': 'Monthly Pro Plan',
        'unit_price': {'amount': '2000', 'currency_code': 'USD'},  # $20.00
        'billing_cycle': {'interval': 'month', 'frequency': 1},
    }
).json()
```

## Webhook Handling (Critical)
Never rely on client-side checkout success — always confirm via webhooks:

1. Create a notification destination in Developer Tools > Notifications
2. Subscribe to key events: `transaction.completed`, `subscription.created`, `subscription.updated`, `subscription.canceled`, `subscription.past_due`
3. ALWAYS verify the webhook signature:

```python
import hashlib
import hmac

def verify_paddle_webhook(request):
    signature_header = request.headers.get('Paddle-Signature', '')
    # Parse ts and h1 from header: "ts=1234;h1=abcdef"
    parts = dict(part.split('=', 1) for part in signature_header.split(';'))
    ts = parts.get('ts', '')
    h1 = parts.get('h1', '')
    
    # Build signed payload: timestamp:raw_body
    raw_body = request.body.decode('utf-8')
    signed_payload = f'{ts}:{raw_body}'
    
    # Compute expected signature
    expected = hmac.new(
        PADDLE_WEBHOOK_SECRET.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    if not hmac.compare_digest(h1, expected):
        return HttpResponse(status=400)
    
    event = json.loads(raw_body)
    event_type = event.get('event_type')
    
    if event_type == 'transaction.completed':
        data = event['data']
        custom_data = data.get('custom_data', {})
        # Fulfill order using custom_data['user_id']
    
    return HttpResponse(status=200)
```

4. CRITICAL: Do NOT parse or modify the raw request body before verification — any changes break the signature
5. Use event_id to deduplicate — Paddle may send the same webhook multiple times
6. Return 200 immediately, then process asynchronously

## Security Best Practices
- Never handle raw card data — Paddle.js and checkout handle all PCI-sensitive operations
- Always verify webhook signatures using HMAC-SHA256
- Use HTTPS for all webhook endpoints
- Store custom_data references (your internal IDs) in checkout to link Paddle transactions to your records
- Use sandbox environment for all development and testing

## Testing
- Use sandbox environment: set environment to 'sandbox' in Paddle.Initialize
- Sandbox dashboard: sandbox-sellers.paddle.com
- Paddle provides webhook simulation to test your handlers
- Test subscription lifecycle: creation, renewal, past_due, cancellation
- Test with different currencies and tax jurisdictions

## Common Gotchas
- Amounts in Paddle are strings, not integers (e.g., '2000' not 2000) — and represent the smallest currency unit
- Paddle calculates and adds tax on top of your price — the customer pays price + tax, you receive price - Paddle fee
- custom_data is your primary way to link Paddle entities to your internal records
- Sandbox and production use different API URLs and client tokens
- Webhook endpoints must respond within 30 seconds or Paddle will retry
- Up to 10 notification destinations allowed — plan your webhook architecture
- Paddle controls refund decisions as MoR — you request refunds, Paddle approves them