# 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.