Prerequisites

• Your Business Entity Merchant Category Code must be filled in
• Adyen webhooks, user permissions, and Response settings must be configured correctly in your Adyen gateway account — incorrect setup will cause renewals and asynchronous payment methods to fail
• Certain features require Adyen's V71 Checkout version, which is feature-flagged in Recurly's system. This requires CVV capture from returning customers via API or Recurly.js — contact [email protected] for details

Limitations

• Asynchronous payment methods may take 48 hours or more for confirmation, depending on the payment method
• Use Recurly.js or the Recurly API for credit and debit card transactions
• SEPA supports EUR payments only — ensure all SEPA transactions are denominated in EUR
• Certain features are unavailable until your account is migrated to the latest version of Adyen — contact [email protected] about enabling V71

Definition

Key details

Setting up Adyen with Recurly

Step 1 — Configure Adyen account credentials

Ensure a webservice user is set up in Adyen so Recurly can dispatch transactions to your gateway.

• 11a — API PCI Payments role: Request that Adyen activate the API PCI Payments role for your web services user. This is not active by default — without it, payments using a raw card number will fail.
• 11b — Disable CVC requirement: If you don't collect CVV codes from returning customers, request that Adyen disable the CVC requirement on your Merchant Account. If you do collect CVV on all customer-initiated transactions, ensure your integration captures and passes the code to Recurly via API when using V71.

Step 2 — Configure Adyen webhooks

Accurate webhook configuration is required for Recurly to receive transaction status updates, metadata updates, recurring tokens, and other critical information. Incorrect setup will cause renewals and asynchronous payment methods to fail.

https://callbacks.recurly.com/adyen/YOUR_RECURLY_SUBDOMAIN

• RECURRING_CONTRACT — Required for tokenized payment methods to function properly
• REPORT_AVAILABLE — Required for notifying when Adyen reports (such as settlement reports for Revenue Recognition) are available
• EXPIRE — Required for proper Authorize and Capture behavior; ensures report syncing when pending authorizations expire before capture
• CAPTURE_FAILED — Required for proper transaction handling, especially when Authorize and Capture are in use
• OFFER_CLOSED — Required when using the iDEAL payment method
• iDEAL details webhook — Required when using iDEAL; see Adyen's webhook types documentation for details
• recurring.token.created / recurring.token.updated / recurring.token.deleted — Required when using Adyen gateway tokens to ensure Recurly receives timely metadata updates when a token changes outside of Recurly

Adyen documents event codes in two places — configure both or webhooks may not fire:

• Standard Webhooks page
• Webhooks Settings page

Step 3 — Adyen additional data configuration

Navigate to Developers → Additional Data in Adyen for all settings in this step. You can configure everything at once. To automatically receive new features in the future, enable all of these fields for a "set it and forget it" approach. If you prefer more control, enable only what's documented here and monitor this page and the Recurly changelog for future updates.

Activation of response fields via API

To enable card data to appear when a token is received via webhook, enable response fields from Adyen. Once a token is received, Adyen returns extra data to populate card brand metadata — including the BIN, last four digits, and expiration date. Enable the following fields:

• Card bin
• Card Summary
• Expiry date

Activation of 3DS results data

To populate 3DS results data in Recurly, enable all four 3DS response detail settings in Developers → Additional Data. This ensures your transaction detail page populates correctly.

Activation of Network Transaction Reference and recurring details

To successfully process Merchant-Initiated Transactions (MIT) across all payment methods — including Google Pay, Apple Pay, and cards — activate Network transaction reference in your Adyen Merchant Account settings. For payment methods that require tokenization, also enable Recurring Details in the same settings area.

Once activated, Adyen generates a unique Network Transaction ID (NTID) and a reusable token (if applicable) for direct integrations. Note that this ID is not visible in Recurly.

Adding Adyen to your Recurly site

Step 1 — Add Adyen in Payment Gateway configuration

Special considerations

Payment methods

Currencies — ISK and CLP

ISK and CLP are zero-decimal currencies, meaning they cannot have partial amounts in cents. Adyen does not handle this automatically, so Recurly appends the necessary 00 decimal places when sending these transactions to Adyen. Do not add the 00 yourself — doing so will overcharge your customers.

Example: If you send an amount of 23, Recurly sends 2300 to Adyen. Whether the plan amount is set to 23 or 23.00, Recurly sends 2300 to Adyen.

Address accuracy

Recurly supports sending shipping addresses to Adyen, but Adyen requires a full, complete address to avoid errors. Recurly will not send partial addresses. If you use Adyen's reporting or fraud services and rely on shipping address data, ensure the customer's shipping address includes all five fields: street address, city, state, country, and postal code. If any field is absent, Recurly omits the entire shipping address.

Payment method specifics

ACH and SEPA reporting setup

Recurly provides an integrated solution for ACH and SEPA transactions through Adyen. Both methods require a special report to be configured.

To initiate the ACH gateway, set it up as an "Adyen ACH" gateway on the Add Payment Gateway page. For SEPA, use the standard Adyen gateway.

Setting up report credentials

Subscribing to the Payment Accounting report for ACH

Enabling NACHA verification

BACS (United Kingdom)

Bankers' Automated Clearing Services (BACS) Direct Debit is a widely used payment method in the United Kingdom, supporting one-time and recurring transactions. Because of chargeback risks, late failure risks, and the asynchronous nature of Direct Debit payments, BACS is not recommended for one-time charges where physical goods are being shipped.

BACS on Adyen runs on Adyen gateway tokens — Recurly does not have access to the underlying payment details. One-time and recurring charges can still occur via Recurly.js and APIs. Creating a BACS Adyen gateway token is only possible via Recurly.js.

BACS compliance

When using Recurly.js, you are responsible for obtaining consent and displaying appropriate regulatory information to the consumer on your website. The consumer must be informed of the amount, due date of future charges, frequency, and your merchant business name at the time of sign-up. Note that Adyen's name will appear on bank statements as "ADYEN RE [Merchant Name]."

SEPA (European Union)

Single Euro Payments Area (SEPA) Direct Debit is a predominant payment method across the EU, facilitating one-time or recurring euro payments using the customer's name and bank account number (IBAN format). It's a strong option for merchants expanding their market reach within the EU.

As required by the SEPA Direct Debit rulebook, merchants must notify customers each time an account debit is made. Recurly automatically dispatches this notification email on your behalf. For details, see the SEPA renewal reminder documentation.

Recurly also supports automated retries for SEPA payments on Adyen. Learn more about SEPA retries.

Direct Debit — Recurly configuration

• Integrate Adyen as your gateway
• Select the BACS checkbox under APMs in Adyen
• Enable EUR currency for SEPA and GBP currency for BACS — see currency addition documentation

Direct Debit — Adyen configuration

• Activate SEPA and/or BACS as needed
• Ensure EUR is available for SEPA transactions and GBP for BACS transactions
• Enable RECURRING_CONTRACT webhooks — a guide is available on Adyen's site

Regional cards — dual-badge support (France, Belgium, Denmark)

Recurly supports three dual-badged card types on Adyen: Cartes Bancaires (France), Dankort (Denmark, DKK only), and Bancontact (Belgium). Dual-badge cards give customers a choice of which network to use — the major network (Visa or Mastercard) or the regional network.

Dual-badge compliance has two requirements: the customer must be given a choice between networks, and the card field must be labeled "Card" (not "Credit card" or "Debit card") since the card field must accept both types without distinction. If you use Recurly.js elements, this is handled automatically. If you're building your own UI, keep these regulations in mind.

To enable Cartes Bancaires, Dankort, or Bancontact:

1. In your Adyen gateway settings, check the card payment methods you want to accept (Cartes Bancaires, Dankort, and/or Bancontact)
2. Integrate Recurly.js using either the cardElement or cardNumberElement parameters — see the Recurly.js documentation and the Dual/Co-Badged Cards guide
3. For Bancontact: also enable SEPA, since Bancontact transactions convert to SEPA for recurring payments. Additional notes:
   • Bancontact cards do not have or require CVV codes
   • Bancontact always requires 3D Secure — ensure this is enabled in your Adyen account and Recurly.js integrations
   • Bancontact does not support separate Authorize and Capture
4. For Dankort: enable the DKK currency in both Adyen and Recurly, as Dankort is only accepted in DKK

Additional notes:

• Cartes Bancaires transactions experience fewer declines when the cardholder's billing address is submitted — ensure your integration captures this for Cartes Bancaires customers
• Bancontact requires SEPA to be enabled at both Adyen and Recurly — see the SEPA setup steps above
• Dankort requires DKK currency to be enabled at both Adyen and Recurly

Indian cards (INR)

Regional mandates in India are not supported on the Adyen gateway. See Recurly's RBI documentation for more information.

Adyen Cash App Pay

Cash App Pay is a US-only digital wallet that lets customers make purchases using their Cash App balance or a linked card or bank account. At checkout, customers select Cash App Pay, scan a QR code, and authorize the payment through the Cash App on their phone. Cash App Pay through Adyen supports USD transactions only.

Cash App Pay requires Adyen's RECURRING_CONTRACT webhooks — see the webhook configuration steps above or Adyen's documentation for details.

Recurly configuration

• Integrate Adyen as your gateway using Recurly.js Alternative Payment Methods
• Enable USD currency — see currency addition documentation
• Check Cash App Pay in your Adyen Payment Gateway settings in Recurly under Alternative Payment Methods

Adyen configuration

• Activate Cash App Pay
• Ensure USD currency is available
• Enable all applicable webhooks — see the webhook configuration steps in Step 2 above

Adyen iDEAL | Wero

iDEAL | Wero is a widely used banking payment option in the Netherlands. During a transaction, customers select their bank from an accessible list of iDEAL | Wero-affiliated banks and are redirected to a unified interface to complete payment.

The initial subscription payment uses iDEAL | Wero; all subsequent recurring payments use SEPA Direct Debit, since iDEAL | Wero does not support recurring payments natively. Communicate this clearly to customers at the point of sign-up.

Recurly configuration

• Integrate Adyen as your gateway
• Activate SEPA for recurring and periodic payments
• Ensure EUR currency is configured
• Refer to the Recurly.js Alternative Payment Methods guide

Adyen configuration

• Activate SEPA for recurring and periodic payments
• Ensure EUR currency is configured
• Enable all applicable webhooks — see the webhook configuration steps above
• Add iDEAL | Wero details webhooks — steps are available on Adyen's site

Restrictions and guidelines

• Free trials via iDEAL | Wero are not permitted due to inherent iDEAL constraints — use SEPA Direct Debit for free trial offers
• iDEAL | Wero cannot be used for subscriptions with a deferred start date
• Chargebacks cannot be managed through iDEAL | Wero
• Recurly's Checkout and Hosted Payment Pages do not support iDEAL | Wero

Adyen Sofort (Klarna Debit Risk)

Sofort (Klarna Debit Risk) is an online banking payment method used in Germany, Austria, Switzerland, and Belgium, supporting EUR, CHF, and GBP currencies. For recurring transactions, Sofort is not viable — SEPA is used instead.

Recurly configuration

• Initiate the Adyen gateway
• Activate SEPA for subsequent payments
• Ensure EUR currency is operational

Adyen configuration

• Ensure the relevant currencies are active
• Add the OFFER_CLOSED event to your Standard webhook — guidance is available on Adyen's site

Restrictions and guidelines

• Free trials are not supported — use SEPA Direct Debit instead
• Sofort (Klarna Debit Risk) cannot be used for subscriptions with a deferred start date
• Chargebacks cannot be managed through Sofort (Klarna Debit Risk)
• Recurly's Hosted Payment Pages do not support Sofort (Klarna Debit Risk)

Adyen Boleto

Boleto Bancário (Boleto) is a popular payment method in Brazil, commonly used by customers without bank accounts. It supports BRL currency. Because Boleto does not support direct recurring transactions, Recurly implements a specialized renewal process.

Recurly configuration

• Activate Brazilian Real (BRL) currency
• Integrate Adyen as your gateway
• Use Recurly.js to add the Boleto payment option to your checkout page
• Create a Boleto-specific email template for recurring payments — this template notifies customers about upcoming payments and provides a link to download the Boleto invoice

Adyen configuration

• Contact your Adyen representative to confirm your account is aligned with a Brazilian entity
• Enable the Boleto payment method in your Adyen account settings
• Ensure Brazilian Real (BRL) is activated in your Adyen account

How Boleto renewals work

1. For each renewal, Recurly automatically generates a recurring invoice. The invoice initially appears as Past Due to account for Boleto processing time.
2. Recurly communicates with the gateway to issue a new Boleto invoice for the renewal amount.
3. The Boleto email template notifies the customer and provides a download link.
4. Once the customer pays the Boleto, the invoice status in Recurly updates to Paid.

Gateway feature support

Adyen Real Time Account Updater (RTAU)

Adyen Real Time Account Updater (RTAU) updates card details and expiration dates in real time during a transaction, which can improve authorization rates and keep renewals running when a customer's card details change.

Adyen returns PCI card data encrypted to Recurly. To process these encrypted updates, you must generate an RSA key in Recurly and provide the public key to Adyen.

Before you start, confirm with Adyen that RTAU is enabled for your account and that you've completed any required agreements.

Eligibility requirements

• You're using raw cards with Adyen as your primary gateway through a supported Recurly API or Recurly.js (not Adyen Web Components)
• You're not using Adyen gateway tokens or network tokens
• You're not using Adyen Third Party Checkout or components through Recurly.js

Recurly configuration — RSA key

Adyen configuration — RSA key and RTAU enablement

The RSA key cannot be configured directly in the Adyen dashboard. Copy the public key from Recurly and provide it to Adyen via a support ticket, including the public key exactly as shown in Recurly. Once Adyen applies the key, RTAU starts working automatically.

How Adyen RTAU works with Recurly Account Updater

If both services are enabled, card updates that arrive through Adyen RTAU will not be sent to Recurly Account Updater. Adyen RTAU supports Visa, Mastercard, and regional American Express only. To continue receiving Discover and additional American Express updates, keep Recurly Account Updater enabled alongside Adyen RTAU.

Adyen RTAU updates may include:

• Card PAN changes — Recurly decrypts the PAN (when an RSA key is set up) and updates the billing information on the account. Because RTAU runs in real time, if Adyen returns a full card update, Adyen uses the updated card to complete the current transaction and Recurly saves it for future use.
  • Example: Visa ending in 1234 is sent for authorization → Adyen attempts Visa 1234, it declines → Adyen requests a real-time update and receives Visa 4567 → Adyen attempts Visa 4567, it approves → Adyen returns the approval and encrypted Visa 4567 for future use.
• Card expiration date changes — Recurly updates the expiration date on file
• Closed account notices — Recurly invalidates the billing information for the account
• Contact customer notices — Recurly does not update billing information but logs the response in Account Activities when a transaction declines

Disabling RSA keys for Adyen RTAU

To stop using Adyen RTAU, revoke the RSA key on each Adyen gateway where it's enabled:

1. Go to Configuration → Payment Gateways
2. On the Adyen gateway, select Options → Manage Keys
3. Revoke the RSA key

Also contact Adyen to disable RTAU on their side. If Recurly Account Updater is enabled, it resumes processing updates for supported card brands after RTAU is disabled.

Adyen Network Tokens

If Adyen is enabled to create network tokens for your merchant account (cards only), Recurly surfaces whether a network token was used on each transaction. If you're using Adyen Third Party Checkout, you'll get network token behavior by default.

You can find this information in:

• Transaction details in the Recurly Admin UI
• Gateway parameter responses through the API

Recurly displays this as a boolean field called Third Party Network Token Used:

• false — a raw Primary Account Number (PAN) or card data was used
• true — a network token was used

If network tokens aren't enabled in your Adyen account, this value will always be false. Token usage is determined by Adyen, not Recurly — contact Adyen support with questions about why a network token was or wasn't used.

Important: Adyen uses network tokenization only for tokenized payment methods. Recurly supports tokenizing cards only when you use Adyen Web Components through Recurly.js.

Revenue Protect and Protect Premium

If you use Revenue Protect or Protect Premium with Adyen, Recurly supports sending the data Adyen needs to evaluate risk and apply your rules.

Protect Premium — custom risk profiles

If you have a paid subscription to Adyen Protect Premium, you can create custom risk profiles in Adyen and pass the profile ID to Recurly when creating subscriptions or one-time charges through the V3 API.

• V3 field: billing_info.adyen_risk_profile_reference_id
• Adyen reference: Create Risk Profiles

Data Recurly sends to support risk decisions

• Billing and shipping address data — See Shipping addresses for setup guidance
• Shipping method and amount — Recurly sends the invoice shipping amount and the shipping method Name value to Adyen — see Shipping methods
• Browser information — Sent when the shopper is routed through 3D Secure; Revenue Protect can evaluate browser-based rules at the gateway
• Shopper data — Email address, phone number, name, IP address (in-session only), and shopper reference. IP addresses are not sent to Adyen on renewals. If shopper details aren't present on the account, they won't be sent.
• Acquisition date — Send account acquisition dates using acquisition.acquired_at in the V3 API. Existing accounts can be backfilled. See the V3 acquired_at field documentation.

Limitations

• Review rules are not supported for Adyen Protect (new risk engine) when using Purchase transactions. If you need Review, use an Authorize and Capture flow where your system controls capture. When using Purchases, use only Allow, Block, or Check for 3DS actions.

Important notes

• Follow customer notification requirements (for example, SEPA renewal notices)
• Recurly can export billing information from Adyen for SEPA subscription renewals
• Recurly sends purchase transactions to Adyen with a capture flag, overriding your Adyen settings

How asynchronous payments work

After a successful purchase with an asynchronous payment method:

1. The subscription is marked Active, but the invoice and transaction remain in Processing until Adyen confirms payment approval
2. Recurly sends a "processing payment" webhook to configured endpoints and a "payment processing" email to customers (if enabled)
3. Adyen's initial return token is "unverified" while the bank confirms the payment
4. Within 48 hours, the token becomes "verified" and additional transactions can proceed
5. Recurly updates the transaction and invoice status based on Adyen's feedback, and sends the relevant webhooks and emails

Dunning and retries: Asynchronous payments require special handling in dunning — see the PayPal eChecks guidance in PayPal payments.

Asynchronous payment methods and webhook reliance

Because asynchronous payment methods such as SEPA and Boleto can take several days to settle, payment processing in Recurly behaves differently than for card payments. Ensure webhooks are configured correctly to avoid stale transaction and invoice statuses.

Billing information updates

Direct customers to Recurly Hosted Pages or build your own API connection for billing information updates. Recurly charges the new billing information a small amount or a zero-dollar verification (depending on your gateway setup). After Adyen approves the authorization or verification, Recurly automatically issues a refund.

IP address allowlist

In some scenarios, Adyen may use additional IP addresses that must be allowlisted in Recurly. Contact [email protected] before moving to production.

API integration with Recurly

In a standard Recurly.js flow, Recurly handles payment authorization. The customer enters billing details first; after authorization, you create the subscription and process the charge.

Troubleshooting