Integration Guides

Adyen Disputes Webhook

This guide details a five-step configuration process in your Adyen account to enable Forter to receive automatic notifications of chargebacks via webhooks. This configuration will streamline the process of chargeback submissions to Forter, ensures Forter’s real-time decisions are based on the latest chargeback data (enhancing Forter’s accuracy), and prevents unnecessary delays in the reimbursement of chargebacks covered by Forter’s Chargeback Guarantee.

Suggest Edits

Pre-Step: Expose the pspReference value in the Validation API or Order Status API
For Post-Auth Integrations: Map the Adyen pspReference value to the gatewayTransactionId field in the Validation API. The exact path to this field is: payment[0].creditCard.paymentGatewayData.gatewayTransactionId.

For Pre-Auth Integrations: Map the Adyen pspReference value to the gatewayTransactionId field in the Order Status API. The relative path to this field is: paymentGatewayData.gatewayTransactionId.

Example:


   "creditCard": {
        "nameOnCard": "John Smith",
        "bin": "424242",
        "lastFourDigits": "4242",
        "countryOfIssuance": "US",
        "expirationMonth": "03",
        "expirationYear": "2025",
        "verificationResults": {
          "authorizationCode": "A33244",
          "avsFullResult": "Y",
          "processorResponseCode": "188502",
          "processorResponseText": "Authorised"
        },
        "cardBrand": "VISA",
        "paymentGatewayData": {
          "gatewayTransactionId": "6525704706182988", // psp Reference
          "gatewayName": "ADYEN_CREDIT"
        },
        "fullResponsePayload": {},
    }

Step 1: Log into the Adyen Portal
Log into the Adyen chargeback portal: https://ca-live.adyen.com/ca/ca/login.shtml

Step 2: Set Up a Standard Notification
Once you have logged in, go to the Developer tab and select the "Webhooks" option and then click on the new "webhook" button.


On the webhook options, select "Standard Notification" and Click on the "Add" Button


Step 3: Enable
By default, the notification will be disabled. Click on the small toggle next to "Disabled" so that the webhook is enabled.


Step 4: Add your Credentials
Description
Under the Description field, add a descriptive title such as "Forter-claims"



Server Configuration
Add and select the following configurations:

URL: Paste the following URL in the URL field: https://api.forter-secure.com/webhooks/adyen/ where is your Forter Site ID (see: https://portal.forter.com/settings/general for full credentials).
Method: JSON
Encryption protocol: TLSv1.2



Events
In the events section, click on the "Show all events" toggle on the upper right-hand corner of the box. This should automatically enable ALL standard events including the following:

  • CHARGEBACK
  • CHARGEBACK_REVERSED
  • NOTIFICATION_OF_CHARGEBACK
  • NOTIFICATION_OF_FRAUD
  • PREARBITRATION_LOST
  • PREARBITRATION_WON
  • REQUEST_FOR_INFORMATION
  • SECOND_CHARGEBACK
  • INFORMATION_SUPPLIED
  • DISPUTE_DEFENSE_PERIOD_ENDED


Step 5: Authentication and Security
Security
In the Basic authentication section, add the following: Username: Please use the Forter Secret Key associated with the Forter SiteId you added in the "Server configuration" section as the value for the Username value. You can find your secret key in the Forter portal credentials page here. Password: The password value should be an empty string ""


Step 6: Generate HMAC Key and send it to Forter


Copy This key, paste it to a .txt file and upload it to your Forter S3 transfer bucket for your Forter Implementations member to securely add to Forter's system.


In the HMAC Key section, click the "Generate" button to generate a unique HMAC key and then click on the "Apply" button. Copy and upload your private credentials under the naming "JCBR-Adyen.txt" to your dedicated Forter S3 subfolder or bucket. The instructions for logging into your dedicated S3 bucket/subfolder can be found at the bottom of the historical data transfer page here.



After you copy your HMAC key, scroll to the bottom of the page and click on the Save changes button.

Step 7: Test Configuration
After your Forter onboarding contact has added your Adyen HMAC secret key, click on the "Test configuration" button on the bottom of the same page. From there, you can select the Adyen account you would like to test. You can select any test event from the dropdown "Event" menu to test.


After clicking the "Test" button, you should see a screen that shows a 200 - Ok Response Code and message that the Event delivered successfully.


Please let your Forter Onboarding team know once you've successfully placed a test notification. If you receive an error message or have any issues with testing the webhook, please reach out to [email protected] for further troubleshooting.

Multiple Adyen Accounts
If you have multiple instances of your website on your Adyen account and a single Forter portal site, please link all instances to the same webhook.

Adyen for Chargeback Recovery

Please also set up an additional webhook in Adyen for Chargeback Recovery according to these instructions.

Updated 16 days ago

What’s Next