f8cd37ac8c
Includes: API (Express/TypeScript), Astro site, Python workers, document generators, FCC compliance tools, Canada CRTC formation, Ansible infrastructure, and deployment scripts. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
98 lines
3.8 KiB
Markdown
98 lines
3.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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.
|