# Adyen Payments

Adyen is a payment processor that supports cards, wallets, and local payment methods.

**Status: Implemented**

## Overview

Adyen provides similar functionality to Stripe with a server-side API for processing payments. The integration pattern would be similar to our existing Stripe implementation.

## Privacy/Verification Requirements

Like PayPal and Stripe, Adyen requires business verification. However, Adyen's process is generally less invasive than PayPal's:

**What Adyen requires:**
- Business registration documents (company registration, articles of incorporation)
- Proof of identity for account holders (government ID photo)
- Bank account verification for payouts
- Proof of address (utility bill, bank statement)

**What Adyen does NOT require (unlike PayPal):**
- No face scanning / biometric capture
- No selfies or photos of your face
- Auto-verification attempted first before manual document requests

**Onboarding process:**
1. Self-serve signup at adyen.com
2. Adyen attempts automatic verification first
3. If auto-verification fails, they request documents via dashboard
4. Once verified, you can process live payments

Similar KYC (Know Your Customer) requirements as other payment processors, but less invasive than PayPal. If privacy is a priority, use crypto payments (XMR/DOGE) instead.

## Technical Integration

### Python Library

Official library: https://github.com/Adyen/adyen-python-api-library

```bash
pip install Adyen
```

### Basic Usage

```python
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "YOUR_API_KEY"
adyen.client.platform = "test"  # or "live"

# Create payment
result = adyen.checkout.payments_api.payments({
    "amount": {"currency": "USD", "value": 1000},  # $10.00 in cents
    "reference": f"invoice_{invoice.uuid_str}",
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "paymentMethod": {
        "type": "scheme",
        "number": "4111111111111111",
        "expiryMonth": "03",
        "expiryYear": "2030",
        "cvc": "737"
    },
    "returnUrl": "https://your-site.com/checkout/result"
})
```

### Required Credentials

Each shop would need:

| Credential | Description |
|------------|-------------|
| `adyen_api_key` | API key from Adyen dashboard |
| `adyen_merchant_account` | Merchant account identifier |
| `adyen_client_key` | Client-side key for Drop-in/Components |
| `adyen_hmac_key` | HMAC key for webhook verification |

### Webhooks

Adyen uses HMAC-SHA256 for webhook verification:

```python
import hashlib
import hmac
import base64

def verify_hmac(hmac_key, hmac_signature, payload):
    expected = hmac.new(
        binascii.unhexlify(hmac_key),
        payload.encode('utf-8'),
        hashlib.sha256
    ).digest()
    expected_signature = base64.b64encode(expected).decode('utf-8')
    return hmac.compare_digest(hmac_signature, expected_signature)
```

### Key Events

- `AUTHORISATION` - Payment authorized
- `CAPTURE` - Payment captured
- `REFUND` - Refund processed
- `CHARGEBACK` - Dispute/chargeback created

## Implementation Plan

To add Adyen support:

1. Add shop columns: `adyen_api_key`, `adyen_merchant_account`, `adyen_client_key`, `adyen_hmac_key`, `adyen_enabled`
2. Add invoice columns: `adyen_psp_reference` (payment reference)
3. Create checkout view similar to Stripe PaymentIntent flow
4. Add webhook handler with HMAC verification
5. Add shop settings UI for Adyen credentials

## Resources

- Python Library: https://github.com/Adyen/adyen-python-api-library
- Example Integration: https://github.com/adyen-examples/adyen-python-online-payments
- API Explorer: https://docs.adyen.com/api-explorer/
- Build Your Integration: https://docs.adyen.com/online-payments/build-your-integration
- Webhooks: https://docs.adyen.com/development-resources/webhooks

## Comparison with Other Processors

| Feature | Stripe | PayPal | Adyen |
|---------|--------|--------|-------|
| Python Library | `stripe` | `requests` | `Adyen` |
| Webhook Auth | Signature secret | Signature verification API | HMAC-SHA256 |
| Test Mode | `sk_test_*` keys | Sandbox mode | Test merchant account |
| KYC Required | Yes | Yes (invasive) | Yes |
| Self-serve signup | Yes | Yes | Yes |