The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

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 only. There are additional payment methods available, such as SEPA, via our integration with the Adyen Hosted Payment Pages. 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

  • Log in to the Adyen Customer Area.
  • Click “Settings” >> “Users” >> “Add New User”.
  • Create a new user with webservice role. 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.
  • 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.
  • Configure the callbacks URL for the merchant account under “Settings” >> “Server Configuration” >> “Standard Notifications”
You can find your Recurly subdomain by looking at the URL when logged into Recurly. In the example above, "kalekrate" is the subdomain. The Adyen URL for responses for this example customer would be https://callbacks.recurly.com/adyen/kalekrate

You can find your Recurly subdomain by looking at the URL when logged into Recurly. In the example above, "kalekrate" is the subdomain. The Adyen URL for responses for this example customer would be https://callbacks.recurly.com/adyen/kalekrate

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

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://<f96e63be5147-TestCompany>.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.

Whitelisting IP addresses

In some cases, Adyen will use additional IP addresses for certain customers. These IP addresses need to be whitelisted 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 have them whitelisted.

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 2 / Level 3 card data.

Adyen Hosted Payment Pages

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 a billed in SEPA.
  4. ACH - Supported for new customers only.
  5. Qiwi - Supported for one-time purchases only. The customer flow requires entering a code that is sent to them via SMS/Text, which is not supported with our integration for recurring payments.

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. In an upcoming release, Recurly will allow you to select the payment method directly on your own checkout page, simplifying the checkout experience even further.

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
  3. 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"
  1. If you don't yet have a "reporting user" create a new user and select "Report User" for the "User Type":
  1. 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
  1. 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>tuesday@tuesday.com</account_code>
    <email>tuesday@tuesday.com</email>
    <billing_info>
      <first_name>andy</first_name>
      <external_hpp_type>adyen</external_hpp_type>
    </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.
  1. 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 RJS 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.