Adyen Integration

Adyen is an enterprise-grade payment platform that processes payments for many of the world's largest businesses. LostChurn connects to Adyen via API key and processes webhook notifications (Adyen calls these "Standard Notifications") to detect and recover failed recurring payments.

Prerequisites

• An active Adyen account with access to recurring (tokenized) payments
• Access to the Adyen Customer Area or Test Customer Area with admin permissions
• An Adyen API key with permissions for the Checkout and Recurring APIs
• Your Adyen Merchant Account name
• A LostChurn account with at least one workspace created

Connection Steps

1. Log in to the Adyen Customer Area.
2. Navigate to Developers > API credentials.
3. Click Create new credential and select Web service user.
4. Name the credential LostChurn.
5. Under Server settings > Authentication, generate an API key. Copy it immediately.
6. Under Permissions, ensure the following roles are enabled:
   • Checkout webservice role: For creating payments and handling 3D Secure.
   • Recurring webservice role: For managing tokenized payment methods and recurring transactions.
   • Merchant PAL Webservice role: For retrieving transaction details.
7. Click Save.
8. In your LostChurn dashboard, go to Settings > Integrations and click Connect Adyen.
9. Enter your Adyen Merchant Account name, select your Environment (Test or Live), and paste the API key.
10. Click Save and Verify. LostChurn makes a test API call to confirm the credentials are valid.

Webhook Configuration

Adyen uses "Standard Notifications" (webhooks) to push event data to your systems.

1. In the Adyen Customer Area, go to Developers > Webhooks.
2. Click + Webhook and select Standard Notification.
3. Configure the webhook:
   • URL: Set to:

     https://webhooks.lostchurn.com/v1/adyen

   • Active: Toggle to Yes.
   • Method: POST.
   • SSL Version: TLSv1.2 or later.
4. Under Additional settings > Events, ensure the following are enabled:
   • AUTHORISATION (including both successful and failed)
   • CANCELLATION
   • CAPTURE
   • CAPTURE_FAILED
   • REFUND
   • REFUND_FAILED
   • RECURRING_CONTRACT
   • REPORT_AVAILABLE
   • CHARGEBACK
   • CHARGEBACK_REVERSED
   • SECOND_CHARGEBACK
5. Under Security > Basic Authentication, set a username and password. Enter these same values in your LostChurn Adyen integration settings.
6. Under Security > HMAC Key, click Generate. Copy the HMAC key.
7. In your LostChurn dashboard, paste the HMAC key into the Webhook HMAC Key field.
8. Click Save in the Adyen Customer Area.

HMAC Signature Verification

Adyen embeds the HMAC-SHA256 signature inside the notification JSON body at notificationItems[0].NotificationRequestItem.additionalData.hmacSignature (not in an HTTP header). The HMAC key is hex-encoded and must be converted to raw bytes before use.

LostChurn verifies every incoming notification by:

1. Extracting the hmacSignature from the parsed JSON body.
2. Converting your hex-encoded HMAC key to raw bytes.
3. Computing HMAC-SHA256 of the raw request body.
4. Base64-encoding the result and comparing it against the provided signature using a timing-safe comparison.

Notifications without a valid HMAC signature are rejected with a 401 response.

Notification Acknowledgment

Adyen requires webhook endpoints to respond with [accepted] in the response body. LostChurn handles this automatically. If Adyen reports delivery failures, check that no proxy or WAF is modifying LostChurn's response.

Verify Connection

1. In the Adyen Customer Area, go to Developers > Webhooks and select the LostChurn webhook.
2. Click Test to send a test notification.
3. Adyen reports whether the endpoint responded correctly (HTTP 200 with [accepted] body).
4. In your LostChurn dashboard, navigate to Events and confirm the test notification appears.
5. For a more realistic test, process a test payment in the Adyen Test environment using one of Adyen's test card numbers:
   • Use card number 4000 0000 0000 0002 with any future expiry and CVC 737 to simulate a refusal.

A successful connection shows a green Connected badge on the Adyen card in Settings > Integrations.

Supported Events

Provider-Specific Notes

Test vs. Live Environment

Adyen provides completely separate test and live environments:

• Test (ca-test.adyen.com): Simulated transactions with test card numbers. No real charges.
• Live (ca-live.adyen.com): Real transactions with real payment methods.

Each environment requires its own API credentials and webhook configuration. You can connect both to LostChurn simultaneously.

Refusal Reason Codes

Adyen provides detailed refusal reason codes in failed AUTHORISATION notifications. LostChurn maps these to its internal decline taxonomy:

• Refused: Generic decline, retry eligible after delay.
• Not Enough Balance: Insufficient funds, retry on a different day.
• Card Expired: Triggers dunning email for payment method update.
• CVC Declined: Requires customer to re-enter payment details.
• 3D Secure Authentication Failed: Sends 3D Secure re-authentication email.
• Issuer Unavailable: Temporary issue, retry within hours.
• Fraud: Blocked by issuer's fraud detection, no automatic retry.

The full mapping of Adyen's 50+ refusal reasons to LostChurn's retry strategies is available in Settings > Integrations > Adyen > Decline Code Mapping.

Tokenization and Shopper Reference

Adyen uses a shopperReference + recurringDetailReference combination to identify stored payment methods. LostChurn uses these identifiers when executing retries to charge the correct stored payment method. Ensure your recurring payment setup includes consistent shopperReference values.

Account Structure

Adyen supports complex account hierarchies with company accounts, merchant accounts, and store-level entities. LostChurn connects at the merchant account level. If you have multiple merchant accounts, connect each one separately in LostChurn. Cross-merchant-account reporting is available in the analytics dashboard.

3D Secure / SCA

For payments that require Strong Customer Authentication (SCA) under PSD2, LostChurn can trigger a 3D Secure authentication flow via email. The customer receives a link to complete authentication, and LostChurn monitors the result via Adyen's notification system.

Rate Limits

Adyen does not publish fixed rate limits but monitors API usage per merchant account. LostChurn distributes retry requests to maintain a steady, low-volume request pattern. If you process extremely high volumes (millions of transactions per month), contact Adyen and LostChurn support to discuss capacity planning.

Notification Reliability

Adyen guarantees at-least-once delivery for notifications, meaning duplicate notifications can occur. LostChurn deduplicates incoming notifications using the pspReference and eventCode combination to ensure each event is processed exactly once.