Adyen - Lago

Lago’s native integration with Adyen supports a wide range of payment options. Supported payment methods include:

Card payments (Visa, Mastercard, CB)
Apple Pay
PayPal
American Express
Amazon Pay
Google Pay

Adyen supports more methods than this list. Check the Adyen payment methods for the full list.

Please ensure that you have added payment methods to your Adyen account before setting up the integration (see Adyen documentation).

Connecting Lago to Adyen

To set up the Adyen integration in Lago from our user interface, follow these steps:

In the side menu of your Lago app, navigate to Settings;
Select the Integrations tab;
Click “Adyen” to create a connection;
Give a name to this connection;
Assign a code for easy identification;
Enter the required connection fields (described in the next section); and
Click Connect to Adyen to confirm the integration.

Adyen connection fields

When connecting Lago to Adyen, you need to provide information for the following fields.

1. API Key (mandatory)

The API Key is a mandatory field and can be found in your Adyen account. Follow these steps to retrieve the API Key:

Go to your Adyen account and navigate to Developers > API Credentials;
On the API Credentials page, create new credentials with a type of Web service user;
Click on the Create credentials button to generate the API Key; and
Copy the API Key and paste it in the corresponding field in Lago. Remember to save the changes.

2. Merchant Account (mandatory)

The Merchant Account is required to ensure that Lago targets the correct Adyen account. To find the Merchant Account:

Go to Settings > Merchant accounts in your Adyen account; and
Copy the Account code of the targeted account you want to use with Lago.

3. Live Prefix (optional)

The Live Prefix represents the prefix url of your live Adyen account. This field is optional. If left empty, you can connect a test account. However, for live accounts, you must provide a Live Prefix. Follow these steps to obtain the Live Prefix:

Go to Developers > API URLs > Prefix in your Adyen account.

4. HMAC Signature (optional)

Adyen’s HMAC signatures are used to protect webhook endpoints and messages created by Adyen. Lago requires this signature to properly decrypt outgoing webhooks from Adyen. To find the HMAC Signature:

Create or edit a webhook in Adyen by accessing Developers > Webhooks;
Choose a webhook, e.g. Standard webhook; and
Under “Security” settings, you can find the HMAC Key.

The Live Prefix and HMAC Signature fields are optional and may not be required depending on your use case.

Setting up Adyen’s payments auto-capture

To enable automatic payment capture in your Adyen account, ensure that you have configured the account settings accordingly. Automatic payment capture allows for immediate processing without manual intervention. Refer to Adyen’s documentation for instructions on setting up auto capture.

Turn on Adyen’s recurring details

In Adyen, to enable recurring payments for a stored payment method, follow these steps:

Go to Developers > Additional Data;
Check the box for Recurring Details; and
Click Save.

The Adyen Additional data page with the Recurring details option checked — Adyen recurring details option

Setting up the Adyen webhook for important events

This step is crucial and mandatory for Lago to receive and process messages from Adyen, enabling functionalities such as customer creation/update, payment processing, and refunds. To configure Adyen webhook and establish communication with Lago, follow the steps below:

Access your Adyen application and navigate to the Developers section;
Select Webhooks and create a new webhook of type Standard;
In the Server configuration section, locate the General settings; and
Copy and paste the following URL: https://api.getlago.com/webhooks/adyen/{{your_organization_id}}?code={{connection_code}}.

You can find your Organization ID in Lago under the Developers section in Lago, specifically in API keys & ID > Organization ID.

To find your connection code, navigate to the Integrations section in Lago and select the appropriate connection code for your Adyen integration.

Please ensure that you complete this setup correctly, as your Adyen integration will not function without this vital step.

Setting Adyen as a payment provider for a customer

To collect payments automatically, the customer must exist in both the Lago and Adyen databases. In Adyen, customers are called Shoppers.

Adding a new customer in Adyen

If the customer does not already exist in Adyen, you can create them in Lago using either the user interface or the API. When providing customer information, please ensure the following:

Set Adyen as the customer’s default payment provider;
Select the Adyen connected account;
Keep the field associated with the Adyen Payment Provider Customer ID empty; and
Enable the option to automatically create the customer in Adyen.

Lago payment provider information with Adyen as the default payment provider, an empty payment provider customer ID and the automatic creation option checked — Adyen as PSP for new customer

Once the customer is added in Lago, they are automatically synchronized with Adyen. Adyen generates a unique Shopper ID, which is stored in Lago. Adyen uses the Lago customer’s external_id as the Shopper ID. Upon successful customer creation, you will receive two webhook messages to keep you informed:

customer.checkout_url_generated: This message includes the checkout URL that provides access to the default payment method. It allows you to perform a pre-authorization payment and store the payment method securely; and
customer.payment_provider_created: This message confirms the successful creation of the customer in Adyen, indicating that the customer’s details have been added to the Adyen database.

You may need to enable Developers -> Additional Data -> Payment -> Recurring details for the customer to be automatically created.

Please note that the customer will be created in Adyen only if the payment method has been stored through the checkout URL and pre-authorization payment.

Using an existing customer from Adyen

If the customer and direct debit mandate already exist in Adyen, you can create the customer record in Lago using either the user interface or the API. Follow these steps when adding customer information:

Set Adyen as the default payment provider for the customer in Lago;
Select the Adyen connected account;
Provide the Adyen Shopper Reference as the Lago Payment provider customer ID.
Disable the option to automatically create the customer in Adyen.

Lago payment provider information with Adyen as the default payment provider and a shopper reference filled in as the payment provider customer ID — Adyen as PSP for existing customer

Redirect URL after checkout

After you connect Adyen, set a success URL where your end customer lands after completing the checkout. If you do not define one, your end customer is redirected to Adyen’s website. You can edit or delete the redirect URL. The change only applies to checkout URLs created afterwards.

URL defined should always begin with http:// or https://.

Adyen Checkout: storing customer’s payment method information

When Lago automatically creates a customer in Adyen, Lago returns a checkout link that your customer uses to store their payment method information. The payload sent by Lago will have the following structure, with the checkout link stored under checkout_url:

{
  "webhook_type": "customer.checkout_url_generated",
  "object_type": "payment_provider_customer_checkout_url",
  "payment_provider_customer_checkout_url": {
    "lago_customer_id": "88d23508-47fd-46bb-a87e-50c50f3cb371",
    "external_customer_id": "hooli_1234",
    "payment_provider": "adyen",
    "payment_provider_code": "adyen_test",
    "checkout_url": "https://test.adyen.link/PLEEA656869B11DF6B"
  }
}

Note: The checkout link automatically expires after 69 days.

With this checkout link, your customers can perform a pre-authorization payment. The pre-authorization does not collect any funds from the customer. Once it is confirmed, Lago sends the payment method details to Adyen, which stores them for future transactions.

Adyen pre-authorization page for a zero amount, with the card fields and the Confirm preauthorization button — Adyen checkout with Lago

Regenerate checkout link on demand

If your end customer has not completed the checkout, or wants to change their saved payment information, generate a new checkout link with the dedicated endpoint.

POST /api/v1/customers/:customer_external_id/checkout_url

The new checkout link is returned in the endpoint response, not through a webhook message. It inherits the same expiration setting as the original one. If the customer is not associated with any payment provider, the response contains an error message.

Creating payments from Lago invoices

When a customer has Adyen defined as their payment provider, Lago triggers a payment in Adyen each time a new invoice is generated. No manual action is needed.

Creating refunds from Lago credit notes

When a customer has Adyen defined as their payment provider, Lago triggers a refund in Adyen each time a refund is initiated through a credit note. No manual action is needed.

Payment disputes

When a chargeback (dispute) is lost in Adyen, Lago marks the relevant invoice as disputed lost. It fills the dispute_lost_at field with the timestamp of the lost dispute. After that update:

The invoice becomes non-voidable;
Generating a credit note is possible; however, refunding the payment back to the original payment method is not permitted; and
The invoice cannot be resent for collection.

Connecting Lago to Adyen

Adyen connection fields

Setting up Adyen’s payments auto-capture

Turn on Adyen’s recurring details

Setting up the Adyen webhook for important events

Setting Adyen as a payment provider for a customer

Adding a new customer in Adyen

Using an existing customer from Adyen

Redirect URL after checkout

Adyen Checkout: storing customer’s payment method information

Regenerate checkout link on demand

Creating payments from Lago invoices

Creating refunds from Lago credit notes

Payment disputes

Watch the demo video