Getting Started

Product Catalog

Customers

Subscriptions

Invoices, Credit Notes and Quotes

Taxes

Payments

Site Configuration

Data Privacy & Security

Data Operations

Reports and Analytics

Integrations

Adyen 

If you are using Adyen.js as your checkout solution and need to be SCA-compliant under the European PSD2 regulation, you may have to additionally integrate Chargebee's 3DS Helper in your checkout to handle 3DS transactions. For more information, take a look at how to integrate 3DS Helper  and support 3DS flows.

Introduction 

Adyen  iis the payments platform of choice for many of the world's leading companies. Its success can be attributed to its ability to offer multiple payment options using a streamlined platform. Adyen provides a modern end-to-end infrastructure with direct connections to international cards networks like Visa and Mastercard while supporting a host of other globally preferred payment methods.

This document will assist you with integrating your Adyen payment gateway with Chargebee.

Choosing Adyen 

Here are a few things to consider before you choose Adyen as your payment solution:

  • Payment Methods: Chargebee supports multiple Adyen payment options including Cards, SEPA, iDEAL,Bancontact, Sofort, Giropay, dotpay, and Apple Pay.
    -Pricing: While Adyen does levy a setup fee, the gateway operates on a tiered pricing model (the more your transactions, the less the fee per transaction). More on Adyen's pricing here .
  • Currency Support: Adyen supports over 140 currencies. Find the complete list of currencies  here.
  • Payment Processing: Adyen processes payment asynchronously. This means that there is a delay between the time that Chargebee makes a payment request and the time that Adyen responds as a result of the request.
Note
  • Adyen processes payments in an asynchronous manner, which means there will be a delay in response from Adyen
  • Collect Invoice On Update Payment Method is not supported for Adyen

Automated Account Updater 

Payment failures and recovery are commonly inconveniences associated with recurring billing businesses. In most cases, payment failures occur as a result of expired or outdated card details.
Adyen utilizes a solution that offers Batch or Real-time automated account updater to reduce payment failures.

Chargebee only supports the Real-time account updater feature to ensure all updates to a customer's card information is updated in Chargebee (in real-time). This is accomplished with the help of card networks and the Adyen gateway.

Prerequisites 

To integrate your Adyen account with Chargebee, you must review the following prerequisites actions before initiating the configuration process:

  • Ensure you have an active Adyen account with access to a test and live site. Read more about Adyen accounts here .
    We recommend that you complete and review the results of the end-to-end integration in your test site prior to transitioning it to your live site.

  • Create your API credentials on Adyen and contact their support team to enable the API PCI Payments Role for your API credentials. Read more here .

  • Contact Adyen support  to enable the recurring contract notifications on your live and test accounts to facilitate recurring payments. Read more here .

  • Enable all applicable payment methods that you intend to offer to your customers in your Adyen account. Read more here .

  • Configuration of Chargebee's Notification[] webhooks on Adyen is mandatory for the integration to function.

Integration Options 

The following options are available to integrate your Adyen Gateway with Chargebee

Integration Method Description PCI Requirements 3DS support Available?
Chargebee API + Adyen Gateway Collection of card information is managed by Chargebee's secure hosted pages and directly passed on to Adyen. Low
Yes
Chargebee JS Chargebee's Hosted Components and Fields  You will use Chargebee's Components to collect card details and Chargebee's temporary token. Low
Yes
Chargebee JS Using Adyen's Web Components+Chargebee.js  Collect Card details using Adyen's hosted fields and tokenize using Chargebee.js Low
Yes
Chargebee JS Using Permanent Token - a token that represents a customer's card details stored in Adyen's vault to process payments. When creating a new token and when converting card details to tokens using: - Hosted Components: Low - Your own Checkout: High Yes
Chargebee JS Raw card details and JS helper for 3DS. However, this will need you to ensure PCI compliance - You will collect raw card details via your custom checkout and pass it to Chargebee.js 3DS Helper to conduct 3DS flow. High Yes
Adyen.js + Chargebee API Using Adyen's Web Components+Chargebee.js  Collect Card details using Adyen's hosted fields and tokenize using Chargebee.js. Low Yes

Configuring your Adyen Account 

Prior to integrating Adyen with Chargebee, you must set up the following configurations within your Adyen account.

Setup Roles/Privileges in Adyen
The Checkout Webservice role when enabled for your Adyen profile facilitates a simple and flexible way to initiate and authorize online payments. Read more about the Adyen Roles here .

Follow the steps below to confirm or enable this:

  1. Log in to the Adyen Customer Area with your company-level account.

  2. Navigate to Developers > API Credentials.

  3. Click Add new credential. If you don't have an API credential yet, select Add new credential and select Webservice as User type.

  4. Click Generate API Key from the Authentication section.

  5. Store the generated API key safely on your system and click Save Generated API Key to enable the API key.

  6. Click Generate Password from the Basic Auth section.

  7. Store the password effectively and click Save Generated Password.
    Note:This password cannot be retrieved at a later time hence you must store this effectively.

  8. Enable the following roles from the Roles and Associated Accounts section:

    • API Client-side Encryption Payments Role
    • Checkout Webservice role
    • Merchant Recurring Role
    • Merchant PAL Webservice
    • Checkout encrypted cardholder data( if you intend to use Adyen's Web components or Adyen.js Integration)
  9. Click the Account tab and enable the correct merchant accounts to the API credential.

  10. Click Save

Enable Capture Delay
The time between the authorization of payment and the capture of payment is called the Capture Delay. Chargebee requires the Capture Delay to be set to Manual in Adyen. Capture delay is configured at the merchant account level. Follow the steps below to complete this action:

  1. Switch to view your merchant account details since this setting applies to the merchant level settings.

  2. Navigate to Accounts > Account Settings.

  3. Select Manual from the Capture Delay drop-down list and click Submit.

Note

Support for Auto Capture workflow - While the Manual capture delay is the recommended and default integration workflow for Chargebee, if you explicitly want to use the Auto capture feature, please contact [email protected]  to enable the Auto capture workflow in our Adyen integration.

Retrieve Account Details
In order to effectively integrate your Adyen payment gateway with Chargebee, you must retrieve the following details from your Adyen account. Review the list below for the details required:

  1. Adyen Merchant Code/Name
    Click the icon at the top-left corner of your profile page to view or search for your merchant name.

  2. User Name
    Navigate to Account > User and retrieve the applicable Web Service username from the list.

  3. Client Key
    Navigate to Developers > API Credentials and click the Web Service username. Review the details and copy the Client Key.

  4. Client-Side Encryption Public key
    Navigate to Developers > API Credentials and click the Web Service username. Review the details and copy the Client-Side Encryption Public Key.

  5. Checkout API Live URL Prefix
    Navigate to Developers > API URLs and make a note of the Checkout API URL.
    For example, if your Live URL is https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com/checkout/v32/payments, then your LIVE URL prefix is 1797a841fbb37ca7-AdyenDemo
    This step is optional for your Live Site

Configuring Adyen your Chargebee site 

Once you've set up your Adyen site configuration you can now move to configure this payment gateway to your Chargebee site. Follow the steps below to complete this process:

  1. Log into your Chargebee site.

  2. Navigate to Settings > Configure Chargebee > Payment Gateways.

  3. Click Add Gateway.

  4. Click Adyen from the list of Gateway options.

  5. Type the details retrieved from the Adyen page to corresponding fields.

  6. Create a username and password to allow your Adyen account to communicate with Chargebee via Notifications.
    Note: This will be used for authentication while configuring webhooks on Adyen.

  7. Click Connect.
    Note: A Notification pop-up displays, proceed to Configure Notifications to continue further.

Configure Webhook Notifications 

All occurrences of events triggered from your Adyen site must be communicated to your Chargebee site via Notifications.

Note

The configuration of the webhook/notifications is mandatory for the integration to work.

Follow the steps below to configure your Chargebee notification webhook on your Adyen site:

  1. Click Copy to copy the Notification URL to your clipboard.

  2. Log into your Adyen account.

  3. Navigate to Developers > Webhooks and click Add Webhook.

  4. Navigate to Standard notification from the All Webhooks list and click Add.

  5. Enter the following details in the Transport section:

    • Paste the URL from Step 1 to the URL field.
    • Select TLSv1.2 from the SSL drop-down list.
    • Click the Active checkbox.
    • Select JSON from the Method drop-down list
  6. Enter the username and password created in the Authentication field to allow Adyen to communicate with your Chargebee site.

  7. Click Save Configuration.

  8. Switch back to your Chargebee site and enable the checkbox to confirm you have added the URL to your Adyen account and click Done.

  9. Contact Adyen's support to enable RECURRING_CONTRACT notifications on your Adyen account to charge customers on a recurring basis. You can skip this step if this is already enabled on your Adyen account.

Additional Configuration 

Based on your choice of integration there are additional settings that must be configured.

Configuring Hosted Pages with Adyen

If you intend to use Chargebee's Hosted Pages for your integration the First Name and Last Name must be configured as mandatory on Chargebee's checkout settings.

Follow the steps below to complete this:

If you intend to use Chargebee's Hosted Pages for your integration then the First Name and Last Name must be configured as mandatory fields on Chargebee's checkout settings.

Follow the steps below to complete this:

  1. Click Settings > Configure Chargebee > Checkout & Self-Serve Portal > Fields > Payments.
  2. Enable First Name and Last Name within the Fields settings.
  3. Click Publish.

3D Secure(3DS) with Adyen
If you choose an integration option that supports 3D Secure (3DS) authentication. Review the checklist below to implement 3DS for your Adyen payment gateway on Chargebee:

  • Verify that 3DS is enabled on your Adyen and Chargebee site.
  • Complete the [link static https://www.chargebee.com/docs/2.0/psd2-sca.html#checklist-for-sca]SCA checklist[] in Chargebee before accepting 3DS payments. This helps recover failed payments without compromising on your revenue.
  • Ensure you are using the latest version of Adyen.js as the older version(Client-side Encryption) is not 3DS-compatible.
  • Enable the Address fields within your Checkout and Self-Serve Portal settings. Follow the steps below to complete this:
    • Navigate to Settings > Configure Chargebee > Checkout and Self Serve Portal > Fields > Payments
    • Toggle to enable Address Fields.
    • Click the Edit icon and confirm Address Line1, Address Line 2, City, Zip, State, and Country are listed as Show from the drop-down list.
    • Click Publish.

Click here  to access the tutorial to implement card payments with 3D Secure flow and create a subscription in Chargebee, using Adyen's Web Components, integrated through Chargebee.js and Chargebee APIs.

Frequently Asked Questions 

Having trouble with your Adyen integration? Review the FAQs below for a solution that best suits your issue. Please contact [email protected]  if your query isn't listed below or need additional assistance.

1. What should I do if my payment status displays "in progress" and does not reflect on Chargebee even after a long time?

Configuring the webhook/notifications hold the key to making sure that your Adyen and Chargebee accounts communicate with each other. We recommend you review your notifications configuration.

2. I have configured my notifications/webhooks.What should I do if the the payment source still displays "Pending Verification".

The recurring_contract feature must be enabled on your Adyen account as a prerequisite. Since this cannot be self-enabled, you must contact Adyen's support to enable this for your account.

3. What happens if I don't enable the recurring_contract webhook on Adyen?

The payment source will continue to be in a pending_verification state and any transaction initiated against this payment source will result in a "Payment details not found" error.

4. How I can resolve the "Payment details not found" notifications?

Failure to enable the recurring_contract webhook on Adyen results in the payment source being in a pending_verification state. Any transaction initiated against this payment source will result in the "Payment details not found" error.

5. Should I configure the notification/webhook for each of my Adyen accounts associated with my Chargebee site?

Yes, you must configure the webhook/notifications for each of your Adyen accounts individually with Chargebee.

6. What should I do for transactions that were processed prior to the correct configuration of the webhook/notifications?

Contact [email protected]  for further steps to guide you resolve this concern.

7. What happens if the API PCI Role is not enabled?

Enabling the API PCI role in your Adyen account is a prerequisite to integrating your Adyen gateway with Chargebee. Failure to complete this will result in restrictions to submit payment requests with raw card data.

8. Why must I enable roles within the Adyen Roles and Account settings?

The roles when not enabled within your Adyen configuration lead to the following errors:

  • Merchant PAL Webservice Role - Inability to make API requests to Adyen.
  • Merchant Recurring role - We cannot vault the payment method in Adyen for recurring payments
  • API Client-side Encryption Payments Role - We cannot process payments via Adyen JS, which is used in both Chargebee Hosted pages and Chargebee.Js.
  • Checkout encrypted cardholder data - Disrupts the use of Adyen drop-in or components for passing cardholder information.
  • Web Service Role - No permission to make payments and vault payment methods in Adyen

9. Why should I configure only the Webservice user type in Adyen?

Adyen has two user types, the Web Service User and Report user

  • Webservice users will provide permissions to make payments and vault payment methods in Adyen (which is required for Chargebee integration).

  • Report users are able to generate reports from Adyen and do not have access fields required to configure the integration with Chargebee.

10. Can I choose other options apart from Manual in my Capture Delay configuration?

  • If Capture delay is not set as Manual and is set to values like No of days or Auto, Chargebee will fail to sync the status of the transaction and will continue to be in progress.
  • If you wish to select Auto you must reach out to [email protected] This ensures when Chargebee receives an authorization webhook for payment, we will mark it as a success because Adyen will not trigger the Capture webhook for the Auto-capture scenario.

11. How long does it take for funds to reach my bank account?

A transaction goes through different statuses before reaching your account. Payment method type also plays a major role when it comes to settlement time. You can refer Adyen's Merchant Manual  for more info.

12.When can I perform a refund for a transaction?

It is not possible to initiate a refund for an In-Progress transaction. You need to wait for the transaction to transition to Success state to initiate a refund.

13.Is there any time after which I cannot perform a refund?

Refund period varies with the payment method type in case of Adyen. You can contact Adyen's Support Channel  for more info.

14.How is dunning handled when Adyen is configured?

For every recurring invoice, dunning is carried over using the setting configured in Chargebee's Settings > Configure Chargebee > Dunning for Online Payments/Dunning for Offline Payments. Unlike normal payments, Adyen processes payments in asynchronous manner, the dunning is initiated only after the transaction has transitioned to Failure state.

Removing payment from an invoice during the dunning period:
If you remove an in-progress transaction from an invoice in dunning, then dunning will be stopped.

Note

Dunning is supported only for card payments. For other payment methods, if a transaction fails, the invoice will be moved to Not Paid state

15.How is Payment Method Status managed in Adyen?

Adyen's API is totally asynchronous, Chargebee makes a request to Adyen and Adyen responds with the result of the action.

When you add/update a payment method by passing either the payment details or checkout parameters, the payment method will move to Pending Verification state, and will move to either Valid or Invalid state based on whether the authorization was successful or not.

Note

Only payment methods in Valid state can be used for future payments.

"

16. How is Transaction Status managed in Adyen?

When you initiate a payment/refund, the transaction will be verified in Adyen. Transaction status will move to in-progress state when verification begins, and will transition to either Success or Failure state based on the notification received from Adyen.

"

17. Why should ‘Capture Delay' be set as ‘Manual' in Adyen?

Payment processing with Adyen occurs in two steps:

  • First, the payment is authorised - Adyen contacts the customer's financial institution, the payment method is validated and funds are set aside for the payment
  • Second, the payment is captured - Adyen sends a request to the financial institution to go ahead and charge the payment method

The advantage of setting the Capture Delay to Manual is that your customer won't be charged twice in the case of an authorization timeout.

18. How Chargebee can help in leveraging Adyen's RevenueProtect Engine?

Chargebee will send the shopper reference and billing address to Adyen as part of every transaction request. This helps you leverage the following RevenueProtect rules:

Was this article helpful?
Loading…