Overview

Required plan

This feature or setting is available to all customers on any Recurly subscription plan.

Limitations

❗️

Minimum processing requirements

Adyen has minimum processing requirements and business models they do not support. Please visit Adyen's website for more information to see if your business qualifies. For questions involving minimum processing requirements, please reach out to Adyen directly.

• Asynchronous payment methods might take 48 hours or more (dependent on the payment method) for confirmation.
• Use Recurly.js or the Recurly API for credit and debit card transactions.
• SEPA supports only EUR payments. Ensure SEPA transactions are in EUR.

Definition

Recurly's integration with Adyen allows businesses to leverage a robust, enterprise-level payment processor known for its extensive worldwide coverage. It simplifies credit/debit card processing, along with other payment methods, ensuring a frictionless experience for end-users.

Note: Visit our guide on testing your gateway configurations in Recurly to ensure your payment processes are set up correctly.

Key details

How asynchronous payments work

• Upon a successful purchase, the subscription is marked "active", but the invoice and transaction remain "processing" until Adyen confirms payment approval.
• Recurly sends a "processing payment" webhook to configured endpoints and a "payment processing" email to customers (if enabled).
• Adyen's initial return token post-billing is "unverified", awaiting bank payment approval.
• Within 48 hours, the token is "verified" after bank confirmation, enabling further transactions.
• The status of the transaction and invoice is updated in Recurly based on Adyen's feedback. Appropriate webhooks and emails are issued to businesses and customers respectively.
• Dunning and Retries: Asynchronous payments require special handling in dunning. Refer to the PayPal eChecks section for detailed insights.

Asynchronous payment methods

Adyen offers various asynchronous payment methods like SEPA and Boleto, which take several days for settlement. Due to this, the payment processing for such methods deviates slightly in Recurly.

For customer billing information updates

For billing information changes, direct customers to Recurly's hosted pages. Recurly charges the new billing info a minimal amount. Once Adyen validates the new info (i.e., approves the purchase), Recurly automatically issues a refund.

IP address allowlist

For certain scenarios, Adyen may employ additional IP addresses. These must be whitelisted in Recurly. Before transitioning to Production, contact Recurly Support for assistance.

API Integration with Recurly

Typically, purchases using Recurly.js involve Recurly handling payments natively. The customer first provides their billing details. Once authorized, you create the subscription and process the charge.

Setting up payments with Adyen

Ensure a webservice user is set up on Adyen to permit Recurly to dispatch transactions to your gateway.

1. Access the Adyen dashboard.

2. Navigate to “Developers” → “API Credentials”.

3. Click "Create new credential".

4. In the modal that appears, select "Web service user" under "Credential Type".

5. Enter your user name and include a description if you wish. For example: Recurly Adyen Credentials

6. Your new credential will be created, and your password will be available under “Server settings” → “Authentication” → “Basic auth” on the subsequent page. You will not be able to access this password after leaving this page, so make note of it immediately. Otherwise, you will need to regenerate the password from this page.
7. Record the auto-generated username and password for later use in Recurly.
8. Click ‘Save changes’.

9. In the "Risk" section under "Dynamic 3D Secure", update the Dynamic 3DS setting to "prefer no" unless you specifically wish to always require 3DS on your Adyen instance. You should not do this on a gateway instance where recurring billing is running
10. For those adhering to the PSD2 Mandate, follow our Adyen-specific guidelines.
11. Request Adyen support to activate the “API PCI Payments role” for your web services user, as it isn't active by default.
12. Additionally, ensure that “Acquirer Result” and “Raw Acquirer Result” are enabled in the API responses.

Webhooks configuration

Accurate configuration of the callbacks URL is pivotal for Recurly to receive apt status updates for transaction records.

1. Navigate to “Developer” >> “Webhooks”.
2. Click “+ Webhook” and find "Standard webhook" and click "Add".
3. Under "Server configuration," locate and click on the pencil icon. In the field provided, enter the URL https://callbacks.recurly.com/adyen/<MERCHANT_SUBDOMAIN>, replacing "<MERCHANT_SUBDOMAIN>" with your Recurly site's actual subdomain. Once done, click on the "Apply" button.

No other settings changes should be made in this section.

Note: If your site is hosted in Recurly's European Union (EU) data centers, use callbacks.eu.recurly.com in place of callbacks.recurly.com.

4. Ensure the "Enabled" toggle is set as shown:

5. Click “Save changes” at the bottom of the page.

Activation of "Network Transaction Reference" value

For effective support of merchant-initiated transaction (MIT) transactions for Recurring and One-Time submissions, activate support for "Network transaction reference" within Adyen's Merchant Account settings. Find this option under "Developers > Additional Data". Post-activation, Adyen will return a unique transaction ID for direct integrations. However, this won't be visible in Recurly.

Configuration in Recurly

1. Add the Adyen gateway: Configuration > Payment Gateways > Add New Gateway.
2. Input the username, password, and merchant account from Adyen.
3. Enter the Custom Endpoint (recommended).
4. Choose Zero Dollar Authorization for all card types.
5. Save your configurations.

For the custom endpoint field in Recurly, input only the specific portion of the endpoint provided by Adyen, not the entire URL. In the testing phase, any value can be input, but it requires updating when transitioning to production.

Adyen ACH

Recurly provides an integrated solution for ACH transactions through Adyen. Delve into the nuances of ACH payments by visiting our dedicated ACH Bank Payments documentation.

Adyen configuration

To integrate the ACH gateway, initiate the 'Adyen ACH' gateway on the "Add Payment Gateway" page.

Moreover, ensure these specific configurations are correctly set to effectively process ACH transactions:

1. Set up the "report credentials". A step-by-step guide is available here.
2. Actively subscribe to the Payment Accounting Report. A detailed process can be found here.
3. Within Adyen, adjust settings to "immediate capture" for transactions.

Note: First/Last name on Checks should not be sent as dashes ( - - ) as this will cause immediate declines.

Dual Badge Card Support

On the Adyen platform, Recurly supports the card type of Cartes Bancaires, a card brand offered to French customers. This type of card is "dual-badged" meaning the customer has a preference of which network they process their transactions and subscriptions with.

Dual Badge Compliance has two factors: choice and a non-distinction policy between credit and debit. Customers must be given a choice between Visa or the dual-badged option, in this case Cartes Bancaires and be given the option to enter their card into a single field labeled 'Card', whether the card is debit or credit. If you are using Recurly.js elements, this is done for you. If you are building your own UI, keep these regulations in mind.

To enable Cartes Bancaires support on your Adyen gateway, ensure you follow the below steps:

1. Within the Adyen gateway settings, ensure Cartes Bancaires is checked as a card payment method you wish to accept.
2. Integrate to Recurly.js using either the cardElement or cardNumberElement parameters. See Recurly.js documentation for instructions on enabling card brand network preference within your implementation.

The customer experience will be: A consumer will enter their card into the card field and if their card offers a choice, they should be presented with the options available to them as applicable to their card. They can select their network preference, and continue with their purchase or subscription sign up.

The same choice will be available when updating a billing info or changing billing information to a different dual-badged card. Cards stored in Recurly will retain that choice for subscription processing.

Note: Cartes Bancaires cards experience less declines when transactions are submitted with the cardholder's billing address. Ensure you are capturing your customers' billing address if they're using a Cartes Bancaires card within your solution.

Adyen SEPA

Single Euro Payments Area (SEPA) Direct Debit stands as a predominant payment mode across the European Union (EU). SEPA is instrumental for merchants aiming to expand their market reach within the EU. This method facilitates one-time or recurring payments in Euros by leveraging the customer's name and bank account number (IBAN format).

As stipulated by the SEPA Direct Debit rulebook, it's imperative for merchants to notify customers each time an account debit is made. To ensure seamless communication, Recurly automatically dispatches an email to the customer. Further details can be accessed here.

Recurly supports automated retries for SEPA payments on Adyen. Learn more about SEPA Retries by visiting our documentation on the feature.

Recurly configuration

In your Recurly platform:

• Integrate Adyen as your gateway.
• Enable the EUR currency. Find out more about currency addition here.

Adyen configuration

Within your Adyen platform:

• Activate SEPA.
• Ensure the EUR currency is available.
• Enable RECURRING_CONTRACT webhooks. A guide is available here.

Adyen iDeal

iDEAL is a widely embraced banking payment option in the Netherlands, representing a significant portion of the region's online transactions. During a transaction using iDEAL on Recurly’s checkout, customers will choose their respective banks from an accessible list of iDEAL-affiliated banks. Subsequently, they will be redirected to their bank's platform to complete the payment process.

It's important to note that the inaugural payment for a subscription employs iDEAL, while subsequent payments utilize SEPA Direct Debit (owing to iDEAL's non-support for recurring payments). It's advisable to clearly communicate to customers that post the initial iDEAL transaction, recurring payments will be managed through SEPA Direct Debit.

Recurly configuration

• Integrate Adyen as the gateway.
• Activate SEPA for periodic payments.
• Ensure the EUR currency is in operation.
• Delve into the Recurly.js development guide here.

Adyen configuration

• Activate SEPA for subsequent payments.
• Ensure the EUR currency is functional.
• Enable RECURRING_CONTRACT webhooks. A guide is available here.
• Incorporate “Ideal details” webhooks. Steps can be found here.

Restrictions and guidelines

• Due to inherent iDEAL constraints, free trials via iDEAL are non-permissible. For free trials, Recurly suggests opting for SEPA Direct Debit.
• iDEAL cannot be used for subscriptions with a deferred commencement date.
• Chargeback management isn't feasible with iDEAL.
• Recurly's Hosted Payment Pages do not support iDEAL.
• For a comprehensive list of limitations, refer here.

Adyen Sofort

Sofort stands out as a preferred online banking payment mechanism in countries like Germany, Austria, Switzerland, and Belgium. This payment method is compatible with EUR, CHF, and GBP currencies.

To transact with Sofort, customers will choose their country, provide their bank details, and finalize the payment after receiving a confirmation from their bank.

For recurring transactions, Sofort isn't viable, and SEPA is utilized instead.

Recurly configuration

• Initiate the Adyen Gateway.
• Activate SEPA for subsequent payments.
• Ensure the EUR currency is operational.
• The Recurly.js developer guide can be accessed here.

Adyen configuration

• Ensure the relevant currencies are active.
• Integrate the OFFER CLOSED event within the Standard webhook. Guidance is available here.

Restrictions and guidelines

• Sofort is being phased out by Klarna and no new merchant accounts can be acquired at this time.
• Inherent limitations in Sofort restrict its use for free trials. For such offers, Recurly suggests SEPA Direct Debit.
• Sofort isn't compatible with subscriptions that have a deferred start.
• Sofort transactions cannot be chargeback managed.
• Recurly’s Hosted Payment Pages don't support Sofort.
• For a holistic understanding of the limitations, refer here.
• SOFORT is also known as Pay Now via Klarna. This payment method is not the BNPL/Buy Now Pay Later flavor of Klarna.

Adyen Boleto

Boleto Bancário, commonly known as Boleto, a popular payment method in Brazil, is usually utilized by individuals without access to bank accounts. This payment method is compatible with BRL

This guide outlines the steps to integrate Boleto with your payment systems through Adyen and Recurly, focusing on initial setup, checkout integration, and handling recurring payments.

Recurly configuration

• Activate Brazilian Real (BRL) currency.
• Integrate Adyen as a gateway.
• Leverage Recurly JS to integrate the Boleto payment option directly into your checkout page.
• Establish a Boleto-specific email template for recurring payments. This template should be designed to notify shoppers about upcoming payments and provide them with a direct link to download the Boleto invoice.

Adyen configuration

• Contact your Adyen representative to ensure your account is aligned with an entity recognized in Brazil.
• Enable the Boleto payment method within your Adyen account settings.
• Make sure that Brazilian Real (BRL) is activated in your Adyen account.

Restrictions and guidelines

Due to Boleto's nature, which does not support direct recurring transactions, a specialized process is implemented to handle subscription renewals:

• For each renewal, Recurly automatically generates a new recurring invoice. This invoice initially appears as "Past Due" to account for the Boleto payment processing time.
• Recurly then communicates with the payment gateway to issue a new Boleto invoice for the renewal amount.
• Utilize the previously configured Boleto email template to inform customers about the new invoice, providing them with a link to download the Boleto.
• Once the customer pays the Boleto invoice, the status of the invoice in Recurly is updated to "Paid," completing the transaction cycle.
• Consider using Boleto as a method to increase customer balance, offering flexibility in payment options and enhancing customer satisfaction.

Additional configuration

For Adyen to send essential details to Recurly, set up specific features based on your payment method.

Setting up "Report Credentials" for ACH and SEPA:

1. Log into Adyen, choose "Developers" > "API credentials".

2. If there's no "reporting user", create one. Designate it as "Report service user".
3. Save the password generated under “Server Settings” >> “Authentication” >> “Basic auth” prior to saving changes, or you will need to regenerate the password.
4. Enter the credentials in Recurly under "REPORTS USERNAME" and "REPORTS PASSWORD".

Subscribing to the payment accounting report for ACH

1. In Adyen, go to Reports. In the "Finance" section, click on “Payment Accounting" and then “Manage report”. You will see “Automatic (generate on a schedule)” set to Off if you have never enabled it.

2. Select "Automatic" and toggle automatic generation to “On” and set the file type as CSV. Click the ‘X’ to close the dialogue box.

3. If you click “Manage report” again, you can confirm that the report is now automatically generated.

Configuring Adyen notifications for Recurly

1. In Adyen, go to Developers > Webhooks.

2. Click “+ Webhook” using the upper-right blue button.

3. Add these 4 webhook types: Direct-Debit Pending, Generic Pending, Report details, and Standard webhook.
4. Ensure you are entering the correct callback URL in the Server configuration of each webhook. Click “Apply” and then “Save changes” for each webhook you activate.

These payment methods are pivotal for merchants aiming to expand in Europe and other relevant regions. With Recurly’s integration with Adyen, businesses can offer their customers a plethora of payment options, facilitating smoother transactions and increasing conversion rates. For any queries, connect with our support or explore our expansive knowledge base.

Important notes

• Adhere to regulations around customer notifications, like SEPA's renewal notice requirements.
• Recurly can export billing info from Adyen for SEPA subscription renewals.
• Recurly sends purchase transactions to Adyen with a capture flag, overriding your Adyen settings.
• Currently, Recurly's Adyen integration doesn't support Level 3 card data.