> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.omegatheme.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Connect your Adyen account

> Adyen Dispute Management is marked **BETA** in-app — it's live this release while we finish validating, so some steps may change.

Connect your Adyen account so Synctrack can show your Adyen disputes and let you accept or defend them from inside the app. Adyen is the sixth gateway in the Disputes list, after PayPal, Stripe, Shopify Payment, Airwallex and Klarna.

**Time needed:** about 10 minutes, plus 1–3 business days if Adyen Support has to enable dispute access for you.
**Who can do this:** an Adyen Customer Area user with the **Manage API credentials** permission (usually the account admin).

Synctrack only reads and manages your disputes. It never takes payments, issues refunds or changes your users — that's why the key needs only three roles, and none of them touch money.

## Create an API key in Adyen

1. Log in to your **live** Adyen Customer Area and go to **Developers → API credentials**.

![](https://storage.crisp.chat/users/helpdesk/website/-/8/3/8/3/8383e5404a31c000/group-114_ml6i6w.png)
2. Click **Create new credential**, choose **Web service user**, and type `Synctrack` under **Description**. Use a separate credential rather than the one your checkout uses, so you can revoke Synctrack's access without affecting payments.
3. Under **Permissions → Roles**, tick exactly these three roles:
   - **API dispute management** (group: Uncategorized) — to read your disputes and accept or defend them
   - **Management API - Webhooks read and write** (group: Account) — so Synctrack can register its webhook for you
   - **Management API - Accounts read** (group: Account) — so Synctrack can check the key and list your merchant accounts
4. Untick everything else. Adyen ticks several payment roles by default (for example Checkout webservice role, Merchant Recurring role, Payment methods read and write) — Synctrack doesn't need them. Some roles can't be unticked (for example Merchant PAL Webservice role); that's fine, Synctrack still works.
5. Open **Accounts** and select the merchant account your Shopify store uses. If you have several, select each one you want Synctrack to watch. Click **Save changes**.
6. Under **Server settings → Authentication**, click **Generate API key** and copy it right away — Adyen shows it only once.
7. Click **Save changes** again. A new key only starts working after you save. Keep the key private and paste it only into Synctrack.

![](https://storage.crisp.chat/users/helpdesk/website/-/8/3/8/3/8383e5404a31c000/group-115_efne4.png)

**Can't find "API dispute management"?** This is normal — Adyen hides this role until their Support team enables it for your company. It's Adyen's policy, not a Synctrack error.

1. In Customer Area, click the **?** icon at the top right → **Contact support**.
2. Choose the **Integrations** category, then **Integration type: API only**.
3. Fill in the form:
   - **Subject:** `Enable "API dispute management" role for API credential`
   - **API version:** `Disputes API v30, Management API v3`
   - **Merchant account:** the merchant account your Shopify store uses
   - **Description:**

     ```
     Hi Adyen team,

     Please enable the "API dispute management" role for our company account
     so we can assign it to our API credential (Web service user):
     <paste the credential username, e.g. ws_123456@Company.YourCompany>

     We use Synctrack to manage chargebacks from our Shopify store. It uses the
     Disputes API (acceptDispute, defendDispute, supplyDefenseDocument,
     deleteDisputeDefenseDocument, retrieveApplicableDefenseReasons).

     Thank you!
     ```
4. Submit. Adyen usually replies within a few business days and may add the role for you. If not, return to your Synctrack credential and tick it yourself.

## Connect in Synctrack

1. Go to **Settings → Account settings → Payment gateway**, open the **Adyen** tab and find the **Dispute management** card.
2. Click **Connect Adyen**.
![](https://storage.crisp.chat/users/helpdesk/website/-/8/3/8/3/8383e5404a31c000/group-113_1shj9yq.png)

3. Paste the API key and click **Check key**.
![](https://storage.crisp.chat/users/helpdesk/website/-/8/3/8/3/8383e5404a31c000/image-79_djduns.png)

4. Choose the merchant accounts you want to connect (up to 10 at a time).
5. Under **Webhook setup**, keep **Let Synctrack register the webhook (recommended)** and click **Connect**.

![](https://storage.crisp.chat/users/helpdesk/website/-/8/3/8/3/8383e5404a31c000/group-116_o78r9w.png)

Synctrack creates the webhook in Adyen, generates its security (HMAC) key and sends a test event. When you see **"Adyen connected. New disputes will sync automatically."**, you're done.

**Prefer to create the webhook yourself?** Choose **I'll create the webhook myself** in step 5. The key then needs only **API dispute management**.

1. Copy the **Webhook URL** that Synctrack shows.
2. In Adyen Customer Area, go to **Developers → Webhooks → Create new webhook** and choose **Standard webhook**.
3. Paste the URL as the **Server URL** and choose **JSON** as the format.
4. Under **Additional settings → Risk**, turn on **Include the originalReference for CHARGEBACK_REVERSED events**.
5. Under **Security**, click **Generate HMAC key**, copy it, then save the webhook.
6. Back in Synctrack, paste the HMAC key and click **Save HMAC key**.

Only generate the HMAC key once — each new one in Adyen stops the old one, and you'd need to paste the new key into Synctrack again.

## After you connect

- **Only new disputes appear.** Adyen doesn't let apps list disputes that already existed, so Synctrack shows disputes opened or updated after you connected.
- Disputes appear within minutes of Adyen opening them, under **Disputes → Adyen**.
- If Synctrack hasn't received any dispute event 7 days after you connected, it shows a reminder to check that the webhook is still active in **Developers → Webhooks**.
- **To disconnect**, click **Disconnect** on the account card. Synctrack deletes its stored API key and HMAC key; disputes that already synced stay visible. If you created the webhook yourself, also delete it in **Developers → Webhooks**, then you can delete the Synctrack credential in **Developers → API credentials**.

## Troubleshooting

- **This API key is missing the "API dispute management" role** — add the role. If you can't see it, contact Adyen Support (see above).
- **Adyen didn't accept this API key** — the key was mistyped, revoked, or not saved after generating. Generate a new key and click **Save changes** in Adyen.
- **This API key can't access any merchant account** — select your merchant account under **Accounts** on the credential.
- **This API key lacks the "Management API — Accounts read" role** — add the role, or type your merchant account code by hand.
- **Synctrack couldn't register the webhook automatically** — add the **Webhooks read and write** role and try again, or create the webhook yourself.
- **Adyen's test event didn't reach Synctrack** — check that the webhook in **Developers → Webhooks** is active, or connect again.
- **This merchant account is already connected to another Shopify store** — each Adyen merchant account can be connected to one Synctrack store. Disconnect it there first.
- **This API key has more access than Synctrack needs** — optional: remove the extra roles listed. Synctrack works either way.

Related articles: [Respond to an Adyen dispute](https://help.omegatheme.com/en/article/respond-to-an-adyen-dispute-1rmjrp3/)