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, SEPA, iDEAL, and Sofort. 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.

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 currency
• Enable RECURRING_CONTRACT webhooks. See how to enable RECURRING_CONTRACT in the Adyen dashboard here.

Notes / limitations

• Due to iDEAL limitations, merchants cannot accept iDEAL as a payment method for free trials without charging and refunding the customer a €0.10 iDEAL charge. If merchants want to avoid having to charge and refund a customer for 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 demo here: https://www.klarna.com/sofort/
Sofort doesn’t support recurring payments. Instead recurrent payments will be processed through SEPA.

Recurly setup

• You need to setup Adyen gateway
• You need to setup SEPA for recurring payments
• Be sure that EUR currency is enabled in Recurly
• Please see Recurly.js development documentation here.

Adyen setup

• Be sure that required currencies are activated

Notes / limitations

• Due to Sofort limitations, merchants cannot accept Sofort as a payment method for free trials without charging and refunding the customer a €0.10 charge. If merchants want to avoid having to charge and refund a customer for 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 the Adyen HPP cannot have a future start date.
• Sofort is not supported on Recurly Hosted Payment Pages.
• See other limitations here.

Adyen Hosted Payment Pages

❗️

Adyen deprecated its Hosted Payment Pages

Adyen deprecated its Hosted Payment Pages in October 2022.

With Recurly's integration with Adyen's Hosted Payment Pages (HPP), you gain the ability to accept the payment methods currently available via Adyen’s hosted pages for one-time and/or recurring subscription purchases through Recurly. We have done the work of integrating with Adyen's HPP for you so all you need to do is make one simple update to your Recurly integration in order to get access to the local payment methods your customers want to use. If you are interested in using Adyen's HPP through Recurly, please contact Recurly Support.

The payment methods we currently offer on Adyen HPP are:

1. SEPA
2. iDEAL - recurring charges are billed in SEPA.
3. SOFORT (Klarna Instant Bank Transfer) - recurring charges are billed in SEPA.

NOTE:

• Adyen's HPP supports a long list of payment methods. Enabling other payment methods on Adyen HPP beyond those listed above requires additional Recurly engineering effort. Therefore, if you need other payment methods for your business and customer base, please let us know when you contact Support. We will prioritize adding payment methods based based on this demand. (Not all payment methods support recurring payments).
• ACH is a bank payment method available in the United States only. It is distinct and different from other bank payment methods available in other regions or countries, such as SEPA (EU), BACS (UK), and BECS (AU).

How it works

From a customer perspective

From a customer perspective, when paying with a payment method available through the Adyen HPP, the experience is similar to paying with PayPal where the customer is redirected from your checkout page to a new page hosted by Adyen where they select which payment method they want to use, and then they visit the appropriate page to enter their payment info. When they are done entering their payment info, they return to your checkout page.

You can customize the Adyen hosted pages so that it looks and feels like your own checkout page. Review the Adyen HPP skin documentation for information on how to set up and configure their hosted pages.

From a merchant perspective

From a merchant perspective, when the customer lands on your checkout page and indicates that they want to purchase using one of the payment methods available on via the Adyen HPP, you make an API call to Recurly with some details about the customer. We calculate the amount due and pass that along to Adyen when you redirect the customer to the Adyen HPP. When the customer completes the purchase, Adyen provides Recurly with the payment details, and we use the information to update our systems with a record of what happened. For more detailed information on the API integration, please refer to the API integration section of this page.

After your customer completes their purchase, the information about the customer, subscription, invoice and payment is available in Recurly (since Recurly records the payment method returned from Adyen), via the API, and is included in our webhooks. With this information, you can see which payment methods are performing best, and adjust your business accordingly.

For example, on the /transactions page you'll see the payment method used for payments captured via the Adyen HPP listed alongside the payments captured through Recurly.js. This same data appears in the transactions export, the relevant Recurly APIs, and in the relevant Recurly webhooks.

For refunds / voids

Refunds and voids work the same way as other payments captured through Recurly.js

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. Adyen HPP does not support the concept of an "update" to existing billing information, so in fact what will happen is that 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.

A note about asynchronous payment methods

Some of the payment methods available via the Adyen HPP, like SEPA, 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

• In order to correctly reflect the Adyen HPP transaction status in Recurly, it is important that you configure Adyen to send the appropriate notifications and reports to Recurly. Please refer to the "Configuration" section below for details:

Configuration

Enable payment methods

Adyen's HPP supports a long list of payment methods. Contact Adyen and ask them to enable their HPP for the payment methods you are interested in.
NOTE: Be sure that Recurly Support is aware of the payment methods that you want to process before you start processing payments.

• Please note that some of these payment methods available on Adyen's HPP are suitable for recurring payments, and some are not. Look at the "Recurring" column of the tables on the Adyen site. If Recurring = "Yes" then Recurly can use that payment method for subscription purchases and one-time purchases. If Recurring = "No" then Recurly can only use the payment method for one-time purchases.

• If you are accepting credit / debit cards (e.g. Visa, Mastercard, JCB, Diners), these payment methods should be used with the standard Recurly.js implementation. This ensures that Recurly vaults the card information and can provide you with the benefit of using Recurly's Account Updater service should a payment be declined.

Set up a skin code for new purchases

1. In the Adyen portal, navigate to Skins
2. Add a new skin, and give it a description that makes it clear that the skin will be used for the Recurly / Adyen HPP integration
3. In the skin configurations, click the button to "Generate new HMAC key" and copy / paste that value into the "HMAC KEY" field on the Adyen gateway configuration page in Recurly

• Use the "Test Platform" HMAC key for your Recurly sandbox or dev site
• Use the "Live Platform" HMAC key for your Recurly production or live site

4. Enter the following as the "Payment results URL": https://api.recurly.com/js/v1/adyen/finish.
5. Click "Payment options" and enable the payment methods that you want customers to be able to choose. If you don't see a payment method that you want to enable on your HPP, contact Adyen and ask them to make the payment method available.
6. Complete any other configuration you want to make of your skin, and be sure to save all changes

Set up a skin code for payment info updates (e.g. HAM)

You need to set up at least 2 skin codes. The one above is used for your checkout page. The second skin you need to configure is for when your customer wants to update his/her billing information. Repeat the same steps as above, but with the following differences:

1. The skin description should make it clear that this skin is to be used for billing info updates for the Recurly / Adyen HPP integration
2. In the skin configurations, click the button to "Generate new HMAC key" and copy / paste that value into the "HMAC KEY BILLING UPDATES field on the Adyen gateway configuration page in Recurly

• Use the "Test Platform" HMAC key for your Recurly sandbox or dev site
• Use the "Live Platform" HMAC key for your Recurly production or live site

4. Enter the following as the "Payment results URL": SUBDOMAIN.recurly.com/account/adyen_update (replace "SUBDOMAIN" with your Recurly site's subdomain).

Configure the "report credentials"

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

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. When using the Adyen HPP, however, there is no separate authorization of the billing information separate from the purchase of the subscription or one-time product. Instead, by the time the customer finishes interacting with the Adyen HPP, the payment has already been sent, billing information has been saved with Adyen, and the charge has been made. Therefore, in Recurly we need to record the fact that the charge has already happened.

The recommended API integration flow for the Adyen HPP is as follows:

1. Create Pending Purchase using the /purchases endpoint

• Send an API request to v2/purchases/pending with a subscriptions payload. The API request needs to include the data element " <external_hpp_type>adyen</external_hpp_type>"

• On success, the subscription_UUID will be returned and used in subsequent steps.

• The configurations described above are required in order to have a successful response.

• Here is an example of the API request payload - note the <external_hpp_type>adyen</external_hpp_type> field

<purchase>
  <collection_method>automatic</collection_method>
  <currency>USD</currency>
  <customer_notes>Some notes for the customer.</customer_notes>
  <terms_and_conditions>Our company terms and conditions.</terms_and_conditions>
  <vat_reverse_charge_notes>Vat reverse charge notes.</vat_reverse_charge_notes>
  <account>
    <account_code>[email protected]</account_code>
    <email>[email protected]</email>
    <billing_info>
      <first_name>andy</first_name>
      <external_hpp_type>adyen</external_hpp_type>
      <country>US</country>
    </billing_info>
  </account>
  <adjustments>
    <adjustment>
      <product_code>4549449c-5870-4845-b672-1d07f15e87dd</product_code>
      <quantity>1</quantity>
      <revenue_schedule_type>at_invoice</revenue_schedule_type>
      <unit_amount_in_cents>1000</unit_amount_in_cents>
    </adjustment>
  </adjustments>
  <subscriptions>
    <subscription>
        <plan_code>basic</plan_code>
        <quantity>1</quantity>
    </subscription>
    <subscription>
        <plan_code>sobasic</plan_code>
        <quantity>1</quantity>
    </subscription>
  </subscriptions>
  <coupon_codes>
    <coupon_code>coupon1</coupon_code>
  </coupon_codes>
</purchase>

• This will create a record in the Recurly database with serialized information around the account, subscription, invoice, and billing_info. This table is called pending_purchases. This table is invisible to you, as it only serves as a placeholder while we wait for your customer to complete the purchase.

2. Capture & Activate Pending Subscriptions

• Invoke the Adyen HPP Modal via Recurly.js, by passing in the invoiceUuid and skinCode. See example. Recurly will pass along the amount of the purchase, along with the desired currency and other information that Adyen needs in order to know how much to charge the customer.
• Your customer will then enter his/her billing information in order to complete their purchase.
• After a successful capture, Adyen returns an API response to Recurly, confirming that the customer completed the HPP form successfully, how much they were charged, the currency etc... When we get confirmation from Adyen that the customer completed the purchase, we create the account and its associated billing info. In addition, in Recurly App you will now see:

For synchronous transactions:

• An active Subscription
• A successful Transaction with a completed state and appropriate payment logo
• A paid Invoice that is closed
• Saved Billing Information

For asynchronous transactions:

• An active subscription
• A "processing" Transaction with the appropriate payment method logo
• A "processing" Invoice that is open
• Saved Billing Information

Final considerations / notes

• Since Adyen is capturing the billing information, Recurly doesn't vault the payment details for invoices paid for via the Adyen HPP. As a result, subsequent renewals are excluded from the Account Updater service. They are, however, included in any retries should the renewal payment fail with a soft decline reason code.
• Certain payment methods enabled through the Adyen HPP 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, iDEAL, and SOFORT).

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.
• Purchases routed through the Adyen HPP will always result in new accounts being created in Recurly. Existing accounts in Recurly will need to continue using the payment methods available natively in Recurly (e.g. Credit Cards, PayPal, ACH, Amazon Pay etc...).
• Credit and debit card transactions should be processed using Recurly.js and / or the Recurly API, as the Adyen HPP integration does not currently support credit and debit cards.
• Subscriptions purchased through the Adyen HPP cannot have a future start date.
• SEPA only supports payments in EUR. Because of this, SEPA and iDEAL transactions must be charged in EUR to process correctly.