Adyen & alternative payment methods

Adyen credit / debit cards

Recurly is integrated with Adyen to support credit / debit cards. With this new integration, you get access to yet another enterprise-level, global payment processor.

Supported payment methods

The current API integration supports credit/debit cards, ACH, Boleto, iDeal, Sofort, and SEPA. If you are interested in processing other payment methods through Adyen, please contact Recurly Support and tell them specifically which payment methods you wish to accept.

Accepting payments through Adyen

To start processing payments through Recurly and Adyen, you must follow the instructions below on how to configure your account in Adyen and how to configure the Adyen gateway in Recurly.

Configuration in Adyen

Configuring a new webservice user

You need to configure a webservice user in Adyen so that Recurly can submit transactions to your payment gateway.

• Log into the Adyen dashboard.
• Select “Account” >> “API Credentials”.
• Select "Add new credential".
• On the next page, ensure "Webservice" is selected for "User Type".
• A username and password is automatically generated for you. You will need the username and password while configuring your Adyen gateway in Recurly. Note: The password is not visible, so it’s best to change the password and note down the new password for when you enter it in Recurly.

• Ensure that the Webservice user with the "Checkout Webservice role" is enabled.
• Under "Risk" >> "Dynamic 3D Secure", set your Dynamic 3DS setting to "prefer no" NEW as of June 2021
• If you are within scope of the PSD2 Mandate, please be sure to follow our Adyen specific updates
• Have Adyen support enable the “API PCI Payments role” for your web services user. Recurly will process transactions through Adyen by invoking their API’s. The API permission on Adyen merchant accounts is not enabled by default.
• Have Adyen support also enable the “Acquirer Result” and “Raw Acquirer Result” in the API response. The API responses will include CVV and AVS response codes. You will be able to view this data is Recurly transaction details page.

Configuring the callbacks URL

Proper configuration of the callbacks URL is required to ensure transaction records in Recurly receive the appropriate status updates.

• Select “Developer” >> “Webhooks”.

  • Locate "Standard Notification" and select "Add".

• Enter the value https://callbacks.recurly.com/adyen/<MERCHANT_SUBDOMAIN> where "merchant_subdomain" is the subdomain for your Recurly site.

📘

Note: If your Recurly site is hosted in our European Union (EU) data centers you will need to use callbacks.eu.recurly.com instead of callbacks.recurly.com (e.g. https://callbacks.eu.recurly.com/adyen/kalekrate)

• Ensure that the "Active" checkbox is checked per the picture below:

Enable "Network Transaction Reference" Value

In order to properly support merchant-initiated transaction (MIT) exemptions, please be sure to enable support for "Network Transaction Reference" values within your Adyen Merchant Account configuration. This can be done under the "Acquirer" heading via the following: Developers > Additional Data Settings

Once enabled, a new transaction ID value will be returned by Adyen when processing transaction requests, which you may see if you have a direct integration with Adyen (this new value will not be visible within Recurly).

Configuration in Recurly

• Add the Adyen gateway under Configuration >> Payment Gateways >> Add New Gateway
• Provide username, password, and merchant account from Adyen configuration dashboard
• Custom Endpoint (recommended - see below)
• Select Zero Dollar Authorization for all the card types
• Save configuration

Custom Endpoint: Adyen offers custom endpoints to merchants so that your payments are processed without any issues. We strongly recommend that you take advantage of this new Adyen feature.

Custom Endpoint field in Recurly: Adyen will provide you with a URL like this https://.pal-live.adyenpayments.com/pal/servlet/Payment/v18/authorise.

For production, you need to enter this portion of the endpoint into the Custom Endpoint field in Recurly "f96e63be5147-TestCompany" and not the entire URL.

For testing (sandbox Recurly + sandbox Adyen), you can enter any value. For example, you could enter "test" into this field, though please keep in mind that it'll need to be updated later once you're ready to move to production.

IP address Allowlist

In some cases, Adyen will use additional IP addresses for certain customers. These IP addresses need to be allowed in Recurly before transactions can be successfully processed. Please contact Recurly Support before you move your site into Production mode so that we can work with Adyen to get the IP addresses and allow them.

Note: Recurly submits the purchase transactions to Adyen with a flag to capture the payments immediately (overriding your configuration in Adyen).
Note: Recurly's integration with Adyen does not currently support Level 3 card data.

A note about asynchronous payment methods

Many of the payment methods available via the Adyen gateway, like SEPA and Boleto, are asynchronous - i.e. they take several days for the payment to settle. Because of this nature, purchases made with a payment method that is asynchronous are handled slightly differently in Recurly:

• The subscription is marked as "active" as soon as your customer successfully completes their purchase, but since the payment hasn't actually been approved by the customer's bank, the invoice and it's related transaction remain in a "processing" state until Adyen confirms that the payment has been approved.

• At that time, Recurly will issue a "processing payment" webhook to any endpoints you have configured in Recurly.

• At that time, Recurly will also issue a "payment processing" email to your customer (if you have enabled that email).

• Until we receive confirmation from Adyen that the asynchronous payment was actually approved, Adyen will not successfully process any additional payment requests against that billing information.

• Adyen returns a token for Recurly to use for subsequent purchases as soon as the billing information is successfully entered, but the token is in an "unverified" state because the payment hasn't actually been approved by the customer's bank.

• Within 48 hours, Adyen receives confirmation from the customer's bank that the payment has been approved by the customer's bank. When Adyen gets that confirmation, they issue a notification to Recurly that alerts us to the fact that the token is now "verified."

• Only when the token is "verified," can additional purchases and subscription renewals be made against the stored billing information on the account. Before the token is confirmed as being "verified" additional purchases attempted will fail.

• When Adyen receives confirmation from the bank that the payment has been approved:

• Adyen issues a notification to Recurly that the transaction has been approved. At that time, Recurly will update the status of the transaction and invoice in our system with the appropriate status.

• At that time, Recurly will issue you the appropriate webhook (e.g. successful payment & closed invoice, or failed payment and past due invoice).

• At that time, Recurly will also issue the appropriate email to your customer (if you have enabled the email) (e.g. payment confirmation, or payment declined).

• Dunning and retries:

• Invoices paid for with an asynchronous payment method that enter dunning must also be treated differently than invoices paid for with a synchronous payment method. Refer to the description of PayPal eChecks for an example showing the sequence of events and what happens in each step to the invoice and transaction.

• Configuring Adyen to send Recurly the status updates

For customer updates to billing information

If your customer wants to update their billing information (e.g. replace their current SEPA details with new SEPA details) you can direct them to Recurly's hosted pages to make the update. Recurly will charge the new billing info for the minimum amount allowed for the payment method, and when Adyen confirms that the new billing information is valid (i.e. that the new purchase was approved / completed) then Recurly will automatically refund the purchase.

Adyen ACH

Recurly offers support for ACH transactions via Adyen. To learn more about ACH payments, visit our ACH Bank Payments docs page.

To set up your ACH gateway, add the 'Adyen ACH' gateway from the "Add Payment Gateway" page, and complete the process for adding a gateway outlined here.

Also ensure that the configuration outlined below is completed in order to properly process ACH transactions.

1. Configure the "report credentials" (how to)
2. Subscribe to the Payment Accounting Report (how to)
3. Ensure that your configuration in Adyen sets transactions for "immediate capture".

Adyen SEPA

Single Euro Payments Area (SEPA) Direct Debit is a common payment method in the European Union (EU) making SEPA a key payment method for merchants that are looking to do business in the EU. Through SEPA Direct Debit, merchants can process one-off or recurring Euro-denominated payments. In order to debit a customer’s bank account account, merchants must collect the customer’s name and bank account number in IBAN format.

The SEPA Direct Debit rulebook requires merchants to notify their customer each time they debit the customer’s account. For this case, by default, Recurly automatically sends the customer an email. See details here.

Recurly setup
In your Recurly instance, perform the following:

• Configure Adyen as a gateway
• Enable EUR as a currency. See how to add currency here.

Adyen setup
In you Adyen instance, perform the following:

• Enable SEPA
• Enable EUR as a currency
• Enable RECURRING_CONTRACT webhooks. See how to enable RECURRING_CONTRACT in the Adyen dashboard here.

Adyen iDeal

iDEAL is a popular banking payment method in the Netherlands and represents more than 50% of all online transactions in the region. When paying with iDEAL through Recurly’s checkout flow, customers will select their bank from a list of available banks that support iDEAL, login to their bank’s site, and then complete their payment on their bank’s site. You can see a demo of the flow here.

Note the initial payment for a subscription will be processed as iDEAL and recurring payments will be processed as SEPA Direct Debit payments (iDEAL does not support recurring payments so recurring payments MUST be processed as SEPA Direct Debit payments). We recommend informing your customers that any recurring payments occurring after the initial iDEAL payment will be processed as a SEPA Direct Debit payment.

Recurly setup

• Configure Adyen as a gateway
• Enable SEPA for recurring payments
• Enable EUR as a currency
• Please see Recurly.js development documentation here.

Adyen setup

• Enable SEPA in Adyen for recurring payments
• Enable EUR as a currency
• Enable RECURRING_CONTRACT webhooks. See how to enable RECURRING_CONTRACT in the Adyen dashboard here.
• Enable “Ideal details” webhooks. See how to enable an iDeal Details webhook in Adyen here.

Notes / Limitations

• Due to iDEAL limitations, merchants cannot accept iDEAL as a payment method for free trials. If you want to offer a free trial and want to use a direct debit payment method to secure the free trial, Recurly recommends the merchant use SEPA Direct Debit as a payment method for free trials.
• Subscriptions purchased through iDEAL cannot have a future start date.
• Due to iDEAL limitations, chargeback handling is not supported.
• iDEAL is not supported on Recurly Hosted Payment Pages.
• See other limitations here.

Adyen Sofort

Sofort is the popular online banking payment method in Germany, Austria, Switzerland, and Belgium. Sofort supports EUR, CHF, and GBP currencies.

To pay with Sofort, customers should select their country, enter bank details, and confirm the payment with their bank. You can see a demo here.

Sofort doesn’t support recurring payments. Instead recurrent payments will be processed through SEPA.

Recurly setup

• Set up the Adyen Gateway first
• Set up SEPA for recurring payments
• Ensure that EUR currency is enabled in Recurly
• Please see Recurly.js developer documentation here.

Adyen setup

• Ensure the proper currencies are enabled
• Enable the OFFER CLOSED event in the Standard webhook. See how to enable OFFER CLOSED in the Adyen dashboard here.

Notes / limitations

• Due to Sofort limitations, merchants cannot accept Sofort as a payment method for free trials. If merchants want to offer a free trial and want to use a direct debit payment method to secure the free trial, Recurly recommends the merchant use SEPA Direct Debit as a payment method for free trials.
• Sofort is not supported on Recurly Hosted Payment Pages.
• See other limitations here.

Adyen Boleto

See Boleto.

Additional Configuration

To allow your Adyen gateway to report back important details to Recurly, there are a handful of features you need to set up in Adyen depending on the payment method.

Configure the "report credentials" for ACH and SEPA

1. Log into the Adyen portal, select "settings" and "users"

2. If you don't yet have a "reporting user" create a new user and select "Report User" for the "User Type":

3. Enter the report user name in the "REPORTS USERNAME" field in Recurly and the password in the "REPORTS PASSWORD" field in Recurly

Subscribe to the Payment Accounting Report for ACH

1. Navigate to Reports, and scroll down to the "Finance" section of the page
2. Click the "Subscribe" button for the Payment Accounting Report

3. Select "comma-separated value", and click save to subscribe to the report

Configure Adyen to send notifications to Recurly

1. In the Adyen portal, navigate to Settings / Server Communication

• There are 4 notifications that you need to add in Adyen to ensure that Recurly receives all of the updates we need:
  • Direct-Debit Pending Notification
  • Generic Pending Notification
  • Report Notification - NOTE: be sure to select "Report Available"
  • Standard Notification - NOTE: be sure to select "Authorisation":

API Integration with Recurly

The normal flow for registering a purchase using Recurly.js normally begins with a payment natively handled by Recurly, i.e. through Recurly.js, the customer enters their billing information first, and then when we have authorized the billing info and know that it's valid, then, you create the subscription on the account and we charge the billing information on the account for the purchase.

Final considerations / notes

• Certain payment methods enabled through the Adyen have regulations around customer notification (e.g. SEPA requirements about notifying customers about the upcoming renewal). Before you start collecting payments from a new payment method, be sure that your customer experience has been updated to comply with these regulations.
• Recurly supports the exporting of billing info from Adyen into Recurly for recurring subscription renewals for the SEPA payment method (includes SEPA only).

Limitations

• As mentioned above, asynchronous payment methods take up to 48 hours to confirm that the billing information on the account can be used for subsequent payments. Until the account's billing info is verified by Adyen, any payment requests sent to Adyen for subsequent charges and/or new subscriptions on the account will be declined.
• Credit and debit card transactions should be processed using Recurly.js and / or the Recurly API.
• SEPA only supports payments in EUR. Because of this, SEPA transactions must be charged in EUR to process correctly.