make_post_sell/docs/ADYEN.md

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

pip install Adyen

Basic Usage

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:

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