new-site/frappe_adyen/README.md

frappe_adyen

Adyen payment gateway integration for Frappe/ERPNext. Supports Cards, ACH Direct Debit, Klarna, Cash App Pay, and Amazon Pay via the Adyen Sessions API v71.

Features

• Cards — Visa, Mastercard, Amex, Discover via Adyen Drop-in or Components
• ACH Direct Debit — US bank account payments via ach type code
• Klarna — Buy Now Pay Later (Pay Now, Pay Later, Slice It) via klarna, klarna_account, klarna_paynow
• Cash App Pay — cashapp type code
• Amazon Pay — amazonpay type code
• HMAC webhook verification — All incoming Adyen notifications verified against HMAC-SHA256 signature
• Multi-instance — One Adyen Settings doc per payment method grouping; each maps to its own Payment Gateway Account in ERPNext
• Test/Live toggle — Per-instance environment switch; live requires a unique URL prefix from Adyen

Requirements

• Frappe >= 15.0.0
• payments app installed (bench get-app payments)
• Python >= 3.10

Installation

# 1. Get the app
bench get-app frappe_adyen https://github.com/performancewest/frappe_adyen

# 2. Install payments dependency (if not already installed)
bench get-app payments
bench --site <your-site> install-app payments

# 3. Install frappe_adyen
bench --site <your-site> install-app frappe_adyen

Configuration

After installation, navigate to Adyen Settings in the Frappe desk and create one document per payment method group.

Gateway Instances

Instance Name	allowed_payment_methods	Notes
Card	scheme,applepay,googlepay	Credit/debit + wallets
ACH	ach	US bank accounts only
Klarna	klarna,klarna_account,klarna_paynow	Set capture_delay = manual
CashApp	cashapp	Cash App Pay
AmazonPay	amazonpay	Amazon Pay

Configuration Fields

Field	Description
Gateway Name	Instance label shown in Payment Gateway Account (e.g. Card, ACH)
Enabled	Toggle to activate/deactivate this gateway instance
Environment	test or live
Merchant Account	Your Adyen merchant account name from Customer Area
API Key	From Customer Area → Developers → API credentials
Client Key	Optional — for Drop-in or Components frontend integration
Webhook HMAC Key	From Customer Area → Developers → Webhooks → HMAC key
Live URL Prefix	Required for live only — your unique prefix from Adyen (e.g. 1797a841fbb37ca7)
Allowed Payment Methods	Comma-separated Adyen type codes shown to shopper
Blocked Payment Methods	Optional comma-separated type codes to force-hide
Capture Delay	immediate (default) or manual (required for Klarna)
Channel	Web, iOS, or Android

Webhook Setup

1. Log in to Adyen Customer Area
2. Go to Developers → Webhooks → Add webhook
3. Select Standard notification
4. Set the URL to:

   https://<your-frappe-site>/api/method/frappe_adyen.api.adyen_webhook
   

5. Under Security, enable HMAC signature and copy the generated key
6. Paste the HMAC key into the Webhook HMAC Key field of the matching Adyen Settings document
7. Save and activate the webhook in Adyen Customer Area

The /api/method/frappe_adyen.api.adyen_webhook endpoint is exempt from Frappe CSRF protection. All requests are authenticated via HMAC-SHA256 signature verification instead.

Live Environment

For live transactions, Adyen requires a unique URL prefix:

1. In Adyen Customer Area, go to Developers → API credentials
2. Copy your live URL prefix (e.g. 1797a841fbb37ca7-PerformanceWest)
3. Paste it into the Live URL Prefix field in Adyen Settings
4. Set Environment to live

The app constructs the live checkout endpoint as:

https://<live_url_prefix>-checkout-live.adyenpayments.com/checkout/v71/sessions

License

MIT License — Copyright 2026 Performance West Inc.