Adyen

What this integration does

This integration lets you connect your Adyen payment gateway to Chargebee so that Chargebee can collect, vault, and recover recurring payments through Adyen.

This guide is for a developer or billing administrator who is setting up Adyen as a payment gateway on a Chargebee site and needs the configuration to support recurring billing, webhooks, and 3DS authentication.

Here is how the integration works: Chargebee routes payment and tokenization requests to Adyen, Adyen processes them asynchronously, and Adyen reports the outcome back to Chargebee through webhook notifications. Because the response is asynchronous, there is a delay between the time Chargebee sends a request and the time the transaction reaches a final state — which is why webhook configuration is mandatory for the integration to function.

Adyen is a global payment platform with direct connections to international card networks such as Visa and Mastercard, and support for a wide range of regional payment methods.

When to choose Adyen

Adyen is a strong fit when you sell internationally and need broad currency and local payment-method coverage from a single gateway: it supports over 140 currencies and a wide range of region-specific methods (such as iDEAL, Sofort, Alipay, and SEPA) that card-only gateways do not cover. Its tiered pricing lowers the per-transaction fee as your volume grows, which suits higher-volume recurring businesses. The main trade-off compared to synchronous gateways is that Adyen processes payments asynchronously, so your integration must rely on webhook notifications rather than an immediate response.

Consider the following before you choose Adyen as your payment solution:

• Payment methods: Chargebee supports the following payment options via Adyen:

  • Cards
  • ACH Payments
  • Alipay
  • Alipay HK
  • Apple Pay
  • BACS
  • Bancontact
  • GCash
  • Giropay
  • Google Pay
  • GoPay
  • GrabPay
  • iDEAL
  • KakaoPay
  • Klarna Pay Now
  • NaverPay
  • Online Banking Poland
  • PayCo
  • Payconiq by Bancontact
  • PayMe
  • PayPal
  • PayPay
  • SEPA Payments
  • Sofort
  • Swish
  • Trustly
  • TWINT
  • WeChat Pay

• Pricing: Adyen charges a setup fee and operates on a tiered pricing model — the more transactions you process, the lower the fee per transaction. See Adyen's pricing.

• Currency support: Adyen supports over 140 currencies. See the complete list of currencies.

• Payment processing: Adyen processes payments asynchronously. There is a delay between the time Chargebee makes a payment request and the time Adyen responds.

Automated account updater

Payment failures and recovery are common inconveniences for recurring billing businesses. In most cases, payment failures occur because of expired or outdated card details. Adyen offers a batch or real-time automated account updater to reduce these failures.

Chargebee supports only the real-time account updater, so that any update to a customer's card information is reflected in Chargebee in real time. Chargebee accomplishes this with the help of the card networks and the Adyen gateway.

Prerequisites

Complete the following prerequisite actions before you start configuring your Adyen integration:

• Ensure you have an active Adyen account with access to a test and live site. Read more about Adyen accounts here. Complete and review the results of the end-to-end integration on your test site before you move 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.
• Enable the RECURRING_CONTRACT notification for both the Test and Live environments to support recurring payments. Log in to your Customer Area (CA) account, go to Developers > Webhooks > Settings, and enable Recurring contract. By default, merchant accounts inherit the company's settings unless the value is changed at the merchant level.
• Enable all applicable payment methods that you intend to offer your customers in your Adyen account. Read more here.
• Configure Chargebee's notification webhooks on Adyen. This is mandatory for the integration to function.

Integration options

What's supported and what's not

Use this matrix to confirm what the Adyen integration covers before you configure it. "Not supported" capabilities are listed explicitly so you do not design a flow around them.

Configure your Adyen account

Before you integrate Adyen with Chargebee, set up the following configurations within your Adyen account.

Set up roles and privileges in Adyen

The Checkout Webservice role, when enabled for your Adyen profile, provides a simple and flexible way to initiate and authorize online payments. Read more about the Adyen roles here.

To confirm or enable this:

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

2. Go to Developers > API Credentials.

3. Click Create new credential.

4. Select the Credential type as Web service user, and click Create credential.

   

5. On the Configure API Credential page, click Generate API Key in the Authentication section.

   

6. Save the generated API key securely on your system. You will enter it on the configuration page in your Chargebee site.

   

7. Switch to the Basic Auth tab and click Generate Password.

   

8. Store the password securely. Note: This password cannot be retrieved later, so store it securely.

9. Enable Management API - Accounts read in the Accounts section under Roles. Enabling this role is essential for successfully configuring Adyen in your Chargebee site.

   

10. Enable the following roles in the Uncategorized section under Roles:

    • 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)

      

11. Expand the Accounts section and select the relevant option.

    

12. Click Save changes.

Retrieve your Adyen account details

To integrate your Adyen payment gateway with Chargebee, retrieve the following details from your Adyen account:

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: Go to Account > User and retrieve the applicable Web Service username from the list.

   

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

   

4. Client Key: Go to Developers > API Credentials and click the Web Service username. Review the details and copy the Client Key.

   

5. Checkout API Live URL Prefix: Go to Developers > API URLs and note 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 Sandbox site.

   

Configure Adyen on your Chargebee site

After you set up your Adyen site configuration, configure the payment gateway on your Chargebee site:

1. Log in to your Chargebee site.

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

3. Click Add Gateway.

4. Select Adyen from the list of gateway options.

5. Enter the details you retrieved from Adyen in the corresponding fields.

   

6. Create a username and password to let your Adyen account communicate with Chargebee via notifications. Note: These are used for authentication while configuring webhooks on Adyen.

   

7. Click Connect. Note: A notification pop-up appears; proceed to Configure Notifications to continue.

Configure webhook notifications

All events triggered from your Adyen site must be communicated to your Chargebee site via notifications.

To configure your Chargebee notification webhook on your Adyen site:

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

   

2. Log in to your Adyen account.

3. Go to Developers > Webhooks and click + Webhook.

   

4. Select Standard webhook from the All Webhooks list and click Add.

   

5. Enter the following details in the General > Server Configuration section:

   • Paste the URL from Step 1 into the URL field.

   • Select TLSv1.2 from the SSL drop-down list.

   • Select the Active checkbox.

   • Select JSON from the Method drop-down list.

   • Click Apply.

     

6. Enter the username and password you created earlier in the fields under Security > Basic authentication, to let Adyen communicate with your Chargebee site.

   

7. Click Save changes.

8. Switch back to your Chargebee site, select 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 so you can charge customers on a recurring basis. Skip this step if it is already enabled.

Capture delay setting

The time between the authorization of a payment and the capture of that payment is called the capture delay. When you add and configure the Adyen gateway on your Chargebee site, Chargebee makes an API call to check the capture delay setting in your Adyen account. Chargebee sets the capture delay as Immediate or Manual based on the setting in your Adyen account.

To change the default capture delay setting in your Adyen account (if required):

1. Switch to your merchant account details, because this setting applies at the merchant level.

   

2. Go to Settings > Account Settings.

3. Select Manual or Immediate from the Capture Delay drop-down list, and click Submit. By default, the capture delay is set as Immediate.

   

Sync the capture delay setting

After you configure the capture delay setting in Adyen, verify it in Chargebee:

1. In the Chargebee app, go to Settings > Configure Chargebee and select the already configured Adyen account.

2. On the Configure Adyen page, click Manage.

   

3. The Capture Settings field shows the current capture delay mode selected in your Adyen account.

   

4. If this does not match your current setting in Adyen, or if you have updated it in Adyen:

   a. Refresh the Configure Adyen page in Chargebee and click Manage.

   

   b. Click Connect. The capture delay setting is now synced between Chargebee and Adyen. You can check the Capture Settings using the Manage option again.

   

Additional configuration

Depending on your integration method, configure the additional settings below.

Configure hosted pages with Adyen

If you intend to use Chargebee's hosted pages for your integration, the First Name and Last Name fields must be configured as mandatory in Chargebee's checkout settings.

To complete this:

1. Go to Settings > Configure Chargebee > Checkout & Self-Serve Portal > Fields > Payments.

2. Enable First Name and Last Name within the Fields settings.

3. Click Publish.

   

Set up 3D Secure (3DS) with Adyen

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

• Verify that 3DS is enabled on both your Adyen and Chargebee sites.
• Complete the SCA checklist in Chargebee before accepting 3DS payments. This helps recover failed payments without compromising your revenue.
• Use the latest version of Adyen.js, as the older version (Client-side Encryption) is not 3DS-compatible.
• Allowlist your Chargebee domains in Adyen: add site-name.chargebee.com and site-name.chargebeeportal.com (replace site-name with your actual Chargebee site name) under Allowed Origins in the Adyen dashboard. To do this, go to Developers > API credentials > your username > Client settings > Add allowed origins.
• Enable the Address fields in your Checkout and Self-Serve Portal settings:

  • Go to Settings > Configure Chargebee > Checkout and Self Serve Portal > Fields > Payments.

  • Turn on Address Fields.

  • Click the Edit icon and confirm Address Line 1, Address Line 2, City, Zip, State, and Country are set to Show in the drop-down list.

  • Click Publish.

    

Chargeback management for Adyen

Chargebacks are supported in this integration. To listen to the chargeback webhooks from Adyen, enable the following webhook events in the webhook settings of your Adyen account for full coverage of chargeback notifications:

• CHARGEBACK
• DISPUTE_DEFENSE_PERIOD_ENDED: Contact Adyen support to enable this webhook in your Adyen account. Learn more.
• SECOND_CHARGEBACK

Learn more about Chargeback Management and Configuring Chargeback Management.

Chargebee listens to these chargeback webhooks to handle the post-operations configured in BillingLogiq. The table below maps the gateway statuses to Chargebee's dispute status. For example, if Adyen sends the CHARGEBACK webhook with the status Undefended, Chargebee considers it as INITIATED, and the subsequent operation is triggered based on how you configured Chargebee to handle the entities.

How data behaves

Because Adyen is asynchronous, the integration's behavior at key moments is outcome-changing — review it before you go live.

• Payment and transaction lifecycle: When you initiate a payment or refund, the transaction moves to In Progress while Adyen verifies it, then transitions to Success or Failure based on Adyen's notification. A newly added or updated payment method moves to Pending Verification, then to Valid or Invalid. Only payment methods in the Valid state can be used for future payments.
• Capture delay and settlement: Chargebee sets the capture delay as Immediate or Manual based on your Adyen account setting. If you change the capture delay in Adyen after configuring the gateway without informing Chargebee, transactions can remain unsettled — and because authorized transactions expire after 28 days at Adyen, payments missed for this reason cannot be recovered.
• Dunning: For recurring invoices, dunning uses the setting in Settings > Configure Chargebee > Dunning for Online Payments/Dunning for Offline Payments. Because Adyen is asynchronous, dunning starts only after a transaction transitions to the Failure state. Removing an in-progress transaction from an invoice that is in dunning stops dunning.
• Refunds: You cannot refund an In Progress transaction; wait until it reaches the Success state. The window in which a refund is possible varies by payment method — confirm with Adyen.

Frequently asked questions

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 is key to making sure your Adyen and Chargebee accounts communicate with each other. Review your notification configuration.

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

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

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

The payment source continues to be in a pending_verification state, and any transaction initiated against this payment source results in a "Payment details not found" error.

4. How can I 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 results 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 support for the steps to resolve this.

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. If you do not enable it, you cannot submit payment requests with raw card data.

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

If these roles are not enabled in your Adyen configuration, they lead to the following errors:

• Merchant PAL Webservice Role — Inability to make API requests to Adyen.
• Merchant Recurring role — Chargebee cannot vault the payment method in Adyen for recurring payments.
• 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 the Report user.

• Web Service users have permission to make payments and vault payment methods in Adyen, which is required for the Chargebee integration.
• Report users can generate reports from Adyen but do not have access to the fields required to configure the integration with Chargebee.

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

• If the capture delay is not set as Manual and is set to values like No of days or Auto, Chargebee fails to sync the status of the transaction, which continues to be in progress.
• If you want to select Auto, contact support. This ensures that when Chargebee receives an authorization webhook for a payment, it marks it as a success, because Adyen does 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, and the payment method type plays a major role in settlement time. See Adyen's Payment Status for more information.

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

You cannot initiate a refund for an In-Progress transaction. Wait for the transaction to transition to the Success state to initiate a refund.

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

The refund period varies with the payment method type in Adyen. Contact Adyen's Support Channel for more information.

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. Because Adyen processes payments asynchronously, dunning is initiated only after the transaction transitions to the Failure state.

If you remove an in-progress transaction from an invoice in dunning, dunning is stopped.

15. How is payment method status managed in Adyen?

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

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

16. How is transaction status managed in Adyen?

When you initiate a payment or refund, the transaction is verified in Adyen. The transaction status moves to the in-progress state when verification begins, and then transitions to either the Success or Failure state based on the notification received from Adyen.

17. What happens if I modify the Capture Delay setting in my Adyen account after configuring it in Chargebee?

Ideally, do not modify the Capture Delay setting in your Adyen account after completing the gateway configuration in Chargebee. If you must do so due to unavoidable circumstances, inform Chargebee, and Chargebee will modify a similar setting at the Admin level to avoid negative impacts.

If you do not inform Chargebee after modifying the Capture Delay setting, it can have the following impacts:

• If the Capture Delay is changed from Auto (default setting) to Manual later at Adyen, transactions may remain unsettled after authorization, because Chargebee continues to assume the capture setting is Auto and does not make a Capture call. Chargebee settles the transaction and invoices it, while you would not have received the payment.
• If you realize that you have not received payments after 28 days because of the Capture Delay setting, Chargebee cannot resolve this, because authorized transactions expire after 28 days at Adyen.

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

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

19. Can the Customer ID be sent to Adyen as part of the metadata?

Yes, the integration includes the Customer ID in the metadata sent to Adyen. To find it in your Adyen dashboard, go to the Payments section and select the relevant transaction. Under the Metadata section, the key labeled cb_customer_id contains your Chargebee Customer ID as its value.

20. Does Adyen support Level 2 and Level 3?

Adyen does not support Level 3, but it does support Level 2.

• Because Level 3 is not supported, the option to enable it is not visible on the Adyen gateway configuration page by default.
• To allow access to the Level 2 and Level 3 options in the Chargebee UI, the Payments team must enable this feature manually on request.
• We recommend that merchants use only Level 2, as Level 3 is not officially supported.
• You must also contact Adyen support and request that Level 2 support be enabled on your Adyen account.

21. Does Chargebee support Adyen non-3DS in Full-Page Checkout?

No. Adyen non-3DS is not supported in Full-Page Checkout. To process payments successfully, ensure that 3DS is enabled in the Chargebee Adyen payment configuration.

22. Is the tokenize function supported with the Adyen gateway?

No. The tokenize function is not supported with the Adyen gateway.