Connect Adyen

Adyen connects per brand. You create an API credential and a webhook in your Adyen Customer Area, then paste three values into DisputeDash. After that, new disputes flow in automatically and are defended for you.

What you’ll need

From your Adyen Customer Area:

• API key — an API credential with the API dispute management role.
• Merchant account — the merchantAccount code whose disputes you want to fight.
• Webhook HMAC key — the signing key from a Standard webhook (used to verify inbound notifications).

And admin access to the brand in DisputeDash.

Create the API credential

1. In the Customer Area, go to Developers → API credentials.
2. Create (or open) a credential and make sure it has the API dispute management role.
3. Copy the API key.

Register the webhook

1. In DisputeDash, open Brands → Connections for the brand and start adding an Adyen account — it shows your webhook URL.
2. In the Customer Area, go to Developers → Webhooks → Create webhook → Standard webhook.
3. Paste the DisputeDash webhook URL, enable HMAC signing, and generate an HMAC key — copy it.
4. Subscribe to the dispute events (chargeback and dispute lifecycle — see the webhook reference).

Connect the brand

1. Go to Brands → Connections for the brand (or the Adyen card on the Integrations page).
2. Add an Adyen account and enter:
   • Adyen merchant account — your merchantAccount code.
   • API key — from the step above.
   • Webhook HMAC key — from the step above.
   • Environment — Test or Live.
3. Save. The brand now routes Adyen disputes for that merchant account to DisputeDash.

📷 Screenshot

The Brands → Connections Adyen form (API key, merchant account, HMAC key, environment). Replace this note with: ![Adyen connection](/images/integrations/adyen-connect.png)

How disputes flow in

Once connected, DisputeDash receives Adyen dispute notifications in real time. When a chargeback opens:

1. DisputeDash verifies the webhook’s HMAC signature, creates the case, and maps the card-scheme reason to a dispute category.
2. Evidence is gathered from your connected stack.
3. DisputeDash retrieves the applicable defense reasons, supplies the evidence as defense documents, and defends the dispute through the Disputes API before the deadline.
4. When Adyen resolves the dispute, the case updates to Won or Lost automatically.

Adyen dispute reasons

Adyen delivers the raw card-scheme reason code (Visa dot-notation, Mastercard 4-digit, Amex alphanumeric). DisputeDash maps the common ones to the right evidence set; anything unrecognized appears in Settings → Reason mappings for you to map.

Example reason code	Handled as
Visa 10.4, MC 4837, Amex F10	Fraud
Visa 13.1, MC 4855, Amex C08	Item not received
Visa 13.3, MC 4853, Amex C31	Product unsatisfactory
Visa 13.2, MC 4841, Amex C28	Cancelled subscription
Visa 13.6, MC 4860, Amex C02	Credit not processed
Visa 12.5, MC 4831, Amex P05	Incorrect amount
Visa 12.6.x, Amex P08	Duplicate
MC 4863	Not recognized

Good to know

• Per brand. Connect a separate Adyen merchant account to each brand — one DisputeDash workspace can hold many.
• Test or Live. The environment you choose routes API calls to Adyen’s test or live endpoints. A test connection uses your Adyen test Customer Area, where you can simulate chargebacks end to end.
• Nothing to re-enter. Editing an Adyen account lets you change the environment without re-typing the API key or HMAC key — leave those blank to keep the current values.
• HMAC required. DisputeDash rejects any Adyen notification that fails HMAC verification, so make sure the HMAC key in DisputeDash matches the one on your Standard webhook.