diff --git a/docs/ADYEN.md b/docs/ADYEN.md new file mode 100644 index 0000000..d256c9d --- /dev/null +++ b/docs/ADYEN.md @@ -0,0 +1,119 @@ +# Adyen Payments + +Adyen is a payment processor that supports cards, wallets, and local payment methods. + +**Status: Not yet 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: + +- Business registration documents +- Proof of identity for account holders +- Bank account verification + +Similar KYC (Know Your Customer) requirements as other payment processors. 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 | diff --git a/docs/PAYPAL.md b/docs/PAYPAL.md index 3729b3a..2142f3e 100644 --- a/docs/PAYPAL.md +++ b/docs/PAYPAL.md @@ -2,12 +2,24 @@ PayPal is available as a payment method alongside Stripe and crypto (XMR/DOGE). +## Privacy Warning + +PayPal requires invasive identity verification to receive payments: + +- ML-based face scanning (biometric capture) +- Two images of your face from different angles +- Photos of both sides of government-issued ID (driver's license, passport) +- Business verification for merchant accounts + +This verification is required to move from sandbox to live production payments. There is no way to accept PayPal payments anonymously or privately. If privacy is important to you, consider crypto payments (XMR/DOGE) instead. + ## Shop Setup 1. Go to https://developer.paypal.com/dashboard/ 2. Create an app (sandbox for testing, live for production) -3. Copy Client ID and Secret -4. In Shop Settings → PayPal Settings, enter credentials and save +3. Complete identity verification (face scan + government ID) +4. Copy Client ID and Secret +5. In Shop Settings → PayPal Settings, enter credentials and save ## Configuration