Docs
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.
Adyen is the payment 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.
Here are a few things to consider before you choose Adyen as your payment solution:
A few zero-decimal currencies (IDR, UGX, and more) in Adyen are non-zero-decimal currencies in Chargebee. Therefore, it is recommended that you pass the amount to Chargebee in cents via a Chargebee API. Chargebee supports amounts with up to two decimal places in the major unit of the currency. This amount with 2 decimal places must be converted to an integer by multiplying it with 100.
For example, to specify an amount of 10 IDR, set the amount as (10 x 100) = 1000 cents.
Due to recent world events, you may experience failures for payments originating from Russian financial institutions or instruments. We recommend reviewing guidelines issued by respective payment gateways for additional information.
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.
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 .
Enable RECURRING_CONTRACT notification for both Test and Live environments to facilitate recurring payments. Log into your Customer Area (CA) account, go to Developers > Wehbooks > Settings and enable Recurring contract.
By default, merchant accounts inherit the company's settings unless the setting's value is changed at the merchant level.
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.
The following options are available to integrate your Adyen Gateway with Chargebee
| Integration Method | Description | PCI Requirements | 3DS support Available? |
|---|---|---|---|
| Chargebee API + Adyen Gateway | In this method, collecting card information will have to be handled at your end and has to be passed on to Chargebee. Chargebee then routes this card information directly to Adyen. Since card information will be collected by you directly, you will have to take care of PCI Compliance requirements. | High |
Yes |
| Chargebee JS | Chargebee's Hosted Card Components 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 |
Prior to integrating Adyen with Chargebee, you must set up the following configurations within your Adyen account.
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:
Log in to the Adyen Customer Area with your company-level account.
Navigate to Developers > API Credentials.
Click Create new credential.
Select Crendential type as Web service user type and click Create credential.
On the Configure API Credential page, click Generate API Key from the Authentication section.
Save the generated API key safely on your system. You will have to enter it on the configuration page in your Chargebee site.
Switch to the Basic Auth tab and click Generate Password.
Store the password effectively.
Note:This password cannot be retrieved at a later time hence you must store this effectively.
Enable the Management API - Accounts read from the Accounts section under Roles. Enabling this role is crucial for successfully configuring Adyen in your Chargebee site.
Enable the following roles from the Uncategorized section under Roles:
Expand the Accounts section and select the relevant option.
Click Save changes
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:
Adyen Merchant Code/Name
Click the icon at the top-left corner of your profile page to view or search for your merchant name.
User Name
Navigate to Account > User and retrieve the applicable Web Service username from the list.
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.
Client Key
Navigate to Developers > API Credentials and click the Web Service username. Review the details and copy the Client Key.
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
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:
Log into your Chargebee site.
Navigate to Settings > Configure Chargebee > Payment Gateways.
Click Add Gateway.
Click Adyen from the list of Gateway options.
Enter the details retrieved from the Adyen page to the corresponding fields.
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.
Click Connect.
Note: A Notification pop-up displays, proceed to Configure Notifications to continue further.
All occurrences of events triggered from your Adyen site must be communicated to your Chargebee site via Notifications.
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:
Click Copy to copy the Notification URL to your clipboard.
Log into your Adyen account.
Navigate to Developers > Webhooks and click +Webhook.
Navigate to Standard webhook from the All Webhooks list and click Add.
Enter the following details in the General > Server Configuration section:
Enter the username and password you created in the respective fields under Security > Basic authentication to allow Adyen to communicate with your Chargebee site.
Click Save changes.
Switch back to your Chargebee site and enable the checkbox to confirm you have added the URL to your Adyen account and click Done.
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.
The time between the authorization of payment and the capture of payment is called the Capture Delay. When a merchant adds and configures Adyen gateway to their Chargebee site, Chargebee makes an API call to check the Capture Delay setting in the merchant's Adyen account. The capture delay is set as Immediate or Manual in Chargebee based on the settings in the merchant's Adyen account.
Capture delay settings are configured in Chargebee independently for each Adyen account added to your site. If a merchant adds another Adyen account to their Chargebee site, the capture delay settings will be set as configured for the merchant's new Adyen account being added.
Follow the steps below to change the default capture delay setting in your Adyen account (if required):
Switch to view your merchant account details since this setting applies to the merchant-level settings.
Navigate to Settings > Account Settings.
Select Manual or Immediate from the Capture Delay drop-down list and click Submit. By default, the capture delay is set as Immediate.
Once you have configured the Capture Delay setting in Adyen, you can verify the same in Chargebee by following these steps:
In the Chargebee app, go to Settings > Configure Chargebee > Select the already configured Adyen account.
On the Configure Adyen page, click Manage.
The Capture Settings field shows the current Capture Delay mode selected in your Adyen account.
If this does not match your current setting in Adyen or if you have updated the same in Adyen, follow these steps:
a. Refresh the Configure Adyen page in Chargebee and click Manage.
b. Click Connect. The Capture Delay setting has been synced successfully between Chargebee and Adyen. You can check the Capture Settings using the Manage option again.
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:
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:
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.
Chargebacks are supported this integration. In order to listen to the Chargeback webhooks from Adyen, you can enable the following webhooks events for additional coverage of Chargeback notifications from the webhook settings in your Adyen account:
Learn more about Chargeback Management and Configuring Chargeback Management.
All these webhooks are related to Chargebacks and are listened to by Chargebee to handle post-operations configured in BillingLogiq. The table below defines the mapping of gateway statuses with Chargebee's dispute status.
For example, if Adyen sends the CHARGEBACK webhook with the status undefended, then it is considered as initiated at Chargebee. The subsequent operation is triggered based on how you have configured to handle the Chargebee entities.
| Adyen Webhook | Dispute status in Adyen | Status at Chargebee |
|---|---|---|
| CHARGEBACK | Undefended, Pending | INITIATED |
| CHARGEBACK | Accepted, Lost | LOST |
| DISPUTE_DEFENSE_PERIOD_ENDED | Undefended | INITIATED |
| SECOND_CHARGEBACK | Lost | LOST |
| DISPUTE_DEFENSE_PERIOD_ENDED | Accepted, Lost | LOST |
Having trouble with your Adyen integration? Review the FAQs below for a solution that best suits your issue. Please contact support 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 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 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 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 support 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:
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?
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 Payment Status 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.
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.
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. What happens if a merchant modifies the Capture Delay setting in their Adyen account after configuring their Adyen account in Chargebee?
Ideally, you should not modify the Capture Delay settings in your Adyen account after completing the gateway configuration in Chargebee. If you have to do so due to an unavoidable circumstance, you must inform Chargebee and Chargebee will modify a similar setting at the Admin level to avoid any negative impacts.
If the merchant does 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, the transactions may remain unsettled after authorization as Chargebee will continue to assume the Capture Setting to be Auto and will not make any Capture call. Chargebee will settle the transaction and invoice it at Chargebee, while the merchant would not have received the payment.
If the merchant realizes that they have not received payments after 28 days because of the Capture Delay setting, Chargebee will not be able to resolve this as the authorized transactions expire after 28 days at Adyen.
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:
Field |
Required for |
|
billingAddress |
|
|
shopperReference |
|
