Adyen

Saleor version required: 3.14

The Adyen App is a payment integration app that allows merchants using the Saleor e-commerce platform to accept online payments from customers using Adyen as their payment processor. In addition to processing payments, the Saleor App Payment Adyen provides merchants with tools for managing refunds and chargebacks.

caution

To configure the Adyen App, you must have an account with Adyen.

The Adyen App uses the Adyen Drop-in Advanced Flow and allows for integrations with the following Adyen flows:

• Web (drop-in and components)
• iOS (drop-in and components)
• Android (drop-in and components)
• Cross-platform (React Native drop-in and React Native components)

Features

• Can be configured per channel
• Split refunds and payments
• Givex gift card support

info

Adyen App uses Adyen Checkout API v70 and Management API v1.

If you want to self-host the Adyen app, reach out to our team .

Assumptions

• If Adyen doesn't respond to app request for initialize transaction session or process transaction session with pspReference:
  • App will return CHARGE_ACTION_REQUIRED or AUTHORIZATION_ACTION_REQUIRED as the transaction result. This is because Saleor doesn't require pspReference in app response for these transaction results.
  • App can also return this status if an action is required to be performed on the storefront, this is incicated by an action object being included in the Adyen response.
• App might not return pspReference for:
  • Transaction refund webhook with transaction status of REFUND_FAILURE
  • Transaction charge webhook with transaction status of CHARGE_FAILURE
  • Transaction cancelation webhook with transaction status of CANCEL_FAILURE
  • Initialize transaction session webhook with transaction status of:
    • CHARGE_ACTION_REQUIRED
    • AUTHORIZATION_ACTION_REQUIRED
    • CHARGE_FAILURE
    • AUTHORIZATION_FAILURE
  • Process transaction session webhook with transaction status of:
    • CHARGE_ACTION_REQUIRED
    • AUTHORIZATION_ACTION_REQUIRED
    • CHARGE_FAILURE
    • AUTHORIZATION_FAILURE

Limitations & troubleshooting

Changing channel to configuration mapping in production

App stores it's configuration assigned to specific Saleor channel.

Each payment in Adyen stores channelId in it's metadata, in order to get proper configuration from the app once app receives notification from Adyen.

If you change the this channel to configuration mapping, all enqueued notifications (pending notifications from Adyen) that were related such channel will be not handled properly by the app, causing the request to fail.

Before you change the configuration mapping, make sure that you do one of the following (listed in order of least intrusive changes):

• Create new channel in Saleor and create a new config so that you don't change mappings at all. This way you can gradually accept new orders on new merchant account and keep handling changes related to orders created on old merchant account.
• Use the same webhook settings for the new configuration (HMAC key, username, password).
  • You can re-use old HMAC key in Adyen webhook, by choosing it from the list while creating the webhook.
  • Keep in mind that if you change merchant account app will not be able to request changes on existing Transactions, but it will report changes made in Adyen Dashboard. To do that webhook needs to have selected previous merchant account in "include specific merchant account" setting.
  • If you want to use new HMAC key, remember to first create new configuration in app with the old HMAC key, and then change it in both new and old configuration, then you can save changes in Adyen. This way no notification will be rejected by app due to invalid HMAC signature
• Not recomended: Make sure you don't have any pending notifications in the Adyen queue. You can achieve that by disabling payments for your merchant account for a while and then migrating it.
  • Keep in mind that if you request any action on already created Transactions (refund, charge, cancel), they will fail.
  • Any payment modifications requested in Adyen Dashboard will also not not be reflected in Saleor.

Flooded Adyen webhook queue

Adyen uses a queue to deliver notifications to the app. The more unexpected error occur (app returning non-200 to Adyen), the more events will be marked as "error" in the Adyen queue. Adyen will keep retrying notifications delivery up to 30 days.

After some arbitrary limit set by Adyen is reached for specific webhook events, there is a risk that Adyen will stop sending notifications until error is fixed or notification dropped manually in Adyen Dashboard.

This situation is abnormal, but to ensure smooth process, you should regularly monitor Adyen's webhook queue and drop broken events if needed

In order to drop notifications (e.g. due to a change in channel to configuration mapping in App) refer to Adyen Docs. Keep in mind that if notification is dropeed it's current status won't be reflected in Saleor. You need to drop each broken notification separately by refreshing page in Adyen Dashboard.