DEV Community: Beppe Catanese

Adyen API Diff Tool

Beppe Catanese — Tue, 19 Aug 2025 12:41:00 +0000

APIs evolve quickly with new features, design changes, and deprecations, making it challenging for consumers to keep up. This impact can be significant: developers might miss valuable improvements, misunderstand the behavior of new features, delay the adoption of critical compliance updates.

This is why we have put passion and effort in the Adyen API Diff Tool, a new tool designed to help developers and technical users easily track and compare changes between API versions.

Whether you're maintaining an existing integration or building something new, staying on top of API changes is critical. Previously, this information was scattered across various sources like product announcements, documentation, release notes, and GitHub, resulting in a suboptimal user experience.

This changes today with our new powerful API Diff Tool.

Features

Our goal is simple: to make it easy to understand what’s changed in the Adyen APIs between any two versions.

The Diff Tool includes built-in filters to:

Compare API versions
View changes by version, endpoint and HTTP method
Group changes by endpoint
Spot quickly what’s new, changed, or removed
Focus on Breaking Changes only

Labels, colors, and accordions provide a clean and effective way to visualize the changes. It is embedded directly in the API Explorer. From any specific change in the log, you can easily navigate to the relevant API reference or endpoint details.

Benefits for Developers and other Users

The API Diff Tool is designed to remove uncertainty when working with Adyen APIs. Whether you’re integrating for the first time or upgrading to a new version, it is a valuable tool to:

Understand what changed**: compare any two API versions and see exactly what’s been added, removed, or modified.
Spot breaking changes early**: identify changes that could impact your integration, so you can plan ahead.
Evolve faster and safer**: stay up-to-date with the latest API releases to integrate the new products and features available.
Find what you need more quickly**: go to the API Explorer to find the API reference, the Diff Tool, a lot of examples and code snippets. Everything you need is in one place.

Acknowledgments and Credits

This initiative was a true cross-team effort involving Technical Writers, Developer Relations, and API Champions. We've put significant thought and effort into delivering on our promise of a best-in-class Developer Experience.

A special thank you goes to the open-source project OASDiff, which powers the engine behind our Diff Tool. It enables detailed comparisons between OpenAPI specification files, detects breaking changes, and generates change diffs in multiple formats.

Next Steps: Collect Feedback and Iterate

The API Diff Tool helps developers and integration partners manage API updates more efficiently. It simplifies upgrading to the latest API version, troubleshooting issues, and planning new integrations. By making API changes more transparent, this tool reduces friction and effort during the integration journey, ultimately enhancing the developer experience and accelerating new API adoption.

In the next iteration we will be looking at adding support for webhooks and the option to subscribe to changes.

The Adyen API Diff Tool is now available in our API Explorer! Try it out and share your feedback. We look forward to your input to continue improving.

A Developer’s Guide to HMAC Validation for Adyen Webhooks

Beppe Catanese — Mon, 16 Jun 2025 09:47:44 +0000

Introduction

When it comes to payments, security isn’t optional — it’s essential. If you’re integrating with Adyen, ensuring the incoming webhooks’ authenticity and integrity is very important. That’s where Hash-based Message Authentication Code (HMAC) plays a critical role in securing your Adyen integration.

Implementing, testing, and troubleshooting HMAC validation can be challenging. This guide explains how HMAC validation works, highlights the challenges, and provides tools and best practices for secure and reliable implementation.

HMAC at Adyen

All Adyen webhooks use HMAC to ensure the integrity and authenticity of the payloads delivered to your integrations. The HMAC key should be enabled when setting up a new webhook (either in the Customer Area Webhook page or using the Management API).

Adyen will use the HMAC key to sign the payload by creating an HMAC signature. You must validate the HMAC signature, delivered with the webhook, using the same HMAC key.

Adyen webhooks fall into two main categories, each with its approach to HMAC implementation. Let’s explore the two scenarios.

1. Payments Webhooks

For payments-related webhooks, the calculation of the signature involves using a subset of fields, and it’s embedded directly within the JSON payload under the additionalData object:

{
   "live":"false",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "hmacSignature":"+JWKfq4ynALK+FFzGgHnp1jSMQJMBJeb87dlph24sXw="
            },
          ...
         }
      }
   ]
}

2. Other Webhooks (Adyen for Platforms, Management)

For non-payment webhooks, the signature is calculated using the entire JSON payload. Instead of being included in the payload itself, the signature is provided in the HTTP Header hmacSignature:

content-length: 1614
content-type: application/json
hmacsignature: SMQZFOq3oIdugmf97u9TB+5256jjXgUX3MRjK+RlGNQ=

Implementing HMAC Validation

Developers have two options for implementing HMAC validation: creating their validation function or using the Adyen’s open-source libraries.

Custom Implementation

If you choose to implement your own HMAC validation, you’ll need to follow Adyen’s documentation:

For payments webhooks, follow the Payment webhook HMAC validation guide
For other webhooks, follow the Platform webhook HMAC validation guide

Implementing a custom HMAC validation is not trivial — it requires handling the correct fields in the exact order and matching the encryption algorithm. Instead, use Adyen’s libraries to simplify the process, reducing both effort and risks.

Using Adyen Libraries (Recommended)

Use the Adyen open-source libraries, which provide built-in functions for calculating and validating HMAC signatures. The libraries are thoroughly tested, regularly updated, and available in multiple programming languages (Node.js, PHP, Java, .NET, etc.).

String payload = "....";

// obtain signature
String hmacsignature = headers.get("hmacsignature");
if (hmacsignature == null || hmacsignature.isBlank()) {
   log.warn("HMAC Signature not found");
   throw new RuntimeException("HMAC Signature not found");
}

// perform HMAC validation 
if (!hmacValidator.validateHMAC(payload, hmacsignature, "MY_HMAC_KEY")) {
  throw new RuntimeException("Invalid HMAC signature");
}

Example of Java snippet to validate the HMAC signature

Known Issues and Challenges

HMAC validation errors are, unfortunately, common and challenging to troubleshoot. Several aspects contribute to this complexity:

Propagation delay when updating the HMAC key
Using the correct HMAC key
Unexpected modification of the webhook payload

HMAC Key Update Propagation Delay

When users update (regenerate) the HMAC key associated with a webhook, there’s a delay (up to 10 minutes) before the new HMAC key is fully propagated and used by all webhook components. During this transition period, both the previous and new HMAC keys remain valid.

This delay can lead to validation failures if the implementation isn’t prepared to handle the transition period, especially if you immediately discard the old key when generating a new one.

The best practice here is to maintain both keys temporarily during the transition window.

Using the Correct HMAC Key

One of the most common issues occurs when developers use the HMAC key from a different webhook configuration. With multiple webhooks in use, especially across development, testing, and production environments, it’s easy to mix up which key belongs to which webhook.

Key Check Value (KCV) Verification

The Key Check Value (KCV) is a short hex value derived from the HMAC key that serves as a fingerprint to verify the key (without revealing it).

The KCV is found on the Webhook Configuration page in the Adyen Customer Area (CA). When troubleshooting, always compare the KCV of the HMAC key you’re using with the one displayed in the CA to confirm you’re working with the correct key.

Webhook Configuration page showing the KCV

You can validate the KCV by implementing the following steps:

1. Calculate an 8-digit zero hash (“00000000”) using your HMAC key with the HMAC-SHA256 algorithm

2. Take the last 3 bytes of the resulting hash and convert it to an uppercase hex string

3. Compare this value with the KCV shown in the Customer Area

Adyen’s libraries simplify this process by including scripts to calculate the KCV, making it easy to verify that you’re using the correct HMAC key.

Unexpected Modifications of the Webhook Payload

A common but often overlooked cause of HMAC validation failures is unintentional modification of the webhook payload.

Adyen webhooks deliver information relevant to the customer’s integration (such as references, amounts, etc.) without trimming or encoding data. However, application frameworks and third-party libraries might alter incoming requests in various ways:

Trimming whitespaces
Converting line endings
Normalizing JSON structures
Decoding URL-encoded characters

Check if any infrastructure (web servers, API gateways, proxies) between Adyen and your application could be altering the payload of the incoming HTTP request.

Before any framework processing, capture the raw webhook body and use the proper comparison (byte or string comparison rather than object matching). During your testing, it’s a good practice to test payloads containing special characters and whitespaces to ensure proper handling.

HMAC Validation Troubleshooting

When faced with HMAC validation failures, there are several approaches to troubleshoot and resolve the issue.

Test in Customer Area (CA)

The Adyen Customer Area provides a built-in feature to test your webhook configuration:

Go to Developers -> Webhooks -> Edit webhook
Click on “Test Configuration”
Choose an “Event” type from the dropdown
Click “Test” to send the webhook to your endpoint
Verify the HTTP response is successful by returning a 2xx response status code

This page allows you to edit the webhook payload as needed (for example, changing a reference, amount, or other fields). The HMAC signature will be automatically recalculated and delivered with the new request.

When to use Customer Area Testing

Send webhooks from the Customer Area to verify the end-to-end flow: Adyen sends the webhook, your integration receives the event, and your implementation validates the HMAC signature. This method is ideal for confirming that the entire flow works correctly.

Test with Postman Collection

Our AdyenDev Postman space includes a Postman collection designed explicitly for webhook testing:

1. Fork the Adyen Postman collection to your private workspace

2. Define collection variables, including your HMAC key

3. Update the webhook payload as needed

4. Send the request to your application’s webhook endpoint

The Adyen Webhooks Postman collection contains several sample payloads you can use or modify to simulate webhook events. It automatically calculates the HMAC signature when sending the request.

When to use Postman testing

Use Postman to test webhooks in isolation. This is ideal for validating your implementation without involving the Adyen backend and focusing on how your integration handles webhook events independently.

Test with Adyen Library Scripts

Adyen libraries include built-in methods to calculate the HMAC signature using your HMAC key and JSON payload. Check out the code from GitHub or open the GitHub repository in Codespaces (browser-based development environment), and follow the instructions specific to the library

For example, if you are using the Node API library and need to troubleshoot an issue with the HMAC validation, you can calculate the HMAC signature in 2 simple steps.

First go to the folder that includes the scripts, and install the necessary dependencies:

// go to dir and setup
cd tools/hmac
npm install

Calculate the HMAC signature, passing the JSON payload and the HMAC key:

// run script passing the HMAC key and the JSON file with the payload
node calculateHmacPayments.js 11223344D785FBAE710E7F943F307971BB61B21281C98C9129B3D4018A57B2EB payload.json

⚠️ Important: When reusing a JSON payload, ensure it doesn’t get modified, formatted, or “prettified,” as this would alter the payload and result in a different signature.

Run in Codespaces

You can use effortlessly GitHub Codespaces to run these scripts directly from your browser:

1. Open the GitHub repository for your Adyen library

2. Start a Codespaces workspace

3. In the terminal, navigate to the appropriate directory and run the scripts

@user ➜ cd /tools/hmac
@user ➜ npm install
up to date, audited 8 packages in 477ms

@user ➜ npm list @adyen/api-library
hmac-troubleshooting@1.0.0 /workspaces/adyen-node-api-library/tools/hmac
└── @adyen/api-library@25.0.0

@user ➜ node calculateHmacPayments.js 11223344D785FBAE710E7F943F307971BB61B21281C98C9129B3D4018A57B2EB payload.json

Calculating HMAC signature with payload from 'payload.json'
HMAC signature: qHNSvxCCix79xgBdWemxf0rcNMWoLrMK/4IgMnkOsWI=

When to use Library Built-in Scripts

Use these scripts to troubleshoot HMAC validation failures in applications using the Adyen libraries: verify the expected HMAC signature using your HMAC key and payload.

⚠️ Important: signatures not matching

If your application calculates a different HMAC signature than these scripts, potential issues might include:

Using an outdated version of the library
Using the wrong HMAC key
Working with a modified payload (check for spaces, formatting, and special characters)

Key takeaways for successful HMAC implementation

This article explains HMAC validation, common challenges, and how to troubleshoot issues effectively:

Use Adyen’s open-source libraries to simplify HMAC validation.
Manage HMAC key updates to avoid discarding old keys too early.
Avoid payload modifications to maintain signature integrity.
Leverage Adyen’s testing and troubleshooting tools.

Follow our guidelines and best practices to securely process Adyen webhooks and deliver a seamless payment experience to your shoppers 💚

A Developer's Guide to the new iDEAL

Beppe Catanese — Tue, 10 Sep 2024 15:51:59 +0000

iDEAL, a Dutch payment method that covers bank-to-bank transfers, was launched in 2005 and is the most popular payment method in the Netherlands today.

Shoppers can pay quickly, safely, and easily with iDEAL through their bank's app, internet banking, or by scanning a QR code on their desktop. Whether it's a payment link after a purchase or a payment request from a friend, iDEAL comes in various forms, and the magenta iDEAL logo is synonymous with online payments for many people living in the Netherlands.

As the payment ecosystem rapidly changes, with increasing demand for a smooth checkout experience, iDEAL is also upgrading its infrastructure, flows, and features.

Read this blog to learn what is new in iDEAL 2.0 and what developers need to know.

⚠️ This is a necessary compliance change: all existing payment integrations must be updated by April 1st, 2025.

Features of iDEAL 2.0

New infrastructure

The new infrastructure introduces the iDEAL Hub and a centralized payment page where the users can select their bank. The goal is to facilitate adoption and streamline the onboarding process for banks, issuers, and payment providers. Shoppers will benefit from experiencing a consistent bank selection flow across different web shops, making the process familiar and trusted.

iDEAL profiles

Consumers will be able to save their delivery details and preferred accounts, creating an iDEAL profile via their issuer bank. They can share this information with a webshop, completing the order and payment in one step.

Payment flows

Profiles will help recognize returning users and make the payment faster by offering different options, such as a QR code, the iDEAL payment page, or a one-click payment checkout.

Enabling iDEAL 2.0

The significant change in the iDEAL payment flow is the bank selection process. The list of available banks will no longer be part of the checkout form but will instead be available on the new iDEAL payment page. The checkout page must redirect shoppers to the iDEAL payment page, where iDEAL will handle both bank selection and payment execution.

This is a necessary compliance change that requires all merchants to update the existing integrations.

When adding iDEAL as a new payment method, for example when developing a new payment integration or if you configure a new merchant account, iDEAL 2.0 is enabled by default.

For existing integrations on TEST we have configured the new iDEAL 2.0 payment method next to the existing one: update your payment integration and, when you are ready to test, activate iDEAL 2.0 in your Customer Area.

Update your payment integration

The changes required depend on the type of integration.

API-only

API-only integration is a method of integrating Adyen APIs where developers prefer to handle their checkout forms and user interfaces. This type of integration only requires one change: removing the list of banks from the Checkout page.

Your payment integration must initiate an iDEAL payment using the Adyen Checkout /payments API endpoint. Developers will no longer have to pass the issuer chosen by the shopper:

{
  "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
  "reference":"YOUR_ORDER_NUMBER",
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "paymentMethod":{
    "type":"ideal"
  },
  "returnUrl":"https://your-company.com/checkout?shopperOrder=12xy.."
}

Plugins

When using one our plugins to connect to an existing ecommerce, you only need to upgrade the relevant plugin:

Adyen Magento v9.6.0+
Salesforce Commerce Cloud v24.3.0+

Web Drop-in and Components

Payment integrations that embed the Web Drop-in or Components should upgrade the version of Adyen Web library to v5.65.0 or higher.

The latest Adyen Web versions will no longer display the list of banks to the shopper, but only the redirect button to perform the payment on the iDEAL page.

Good to know

Because the bank selection picklist is no longer provided, you can safely remove any custom validation designed for the previous version of Adyen Components. This is especially important if you have hidden the default Component button and implemented a custom one.
Additionally, note that iDEAL optional configurations from previous versions are no longer available and should be removed.

Check out our sample applications on GitHub to see how to integrate the Web Drop-in and Components, and make a payment with iDEAL.

iOS and Android SDKs

We have updated our iOS and Android mobile SDKs: make sure to use a version released after July 2024.

For iOS, the additional configuration for iDEAL is no longer available and can be removed.

Hosted Checkout

No changes are required.

Activate iDEAL 2.0 in your Customer Area (Existing integrations)

Log into the Customer Area, go to the "Payment methods" screen and select iDEAL with "iDealSim" acquirer. The next step is to click on "More actions" and choose the option "Deactivate". Then select the other iDEAL payment method and activate it to route the iDEAL payments to the new infrastructure.

From then on, all iDEAL payments will be performed using the new protocol.

Save the shopper's preferred bank

The updated iDEAL allows storing the shopper's preferred bank, enabling direct redirection to the bank without requiring the selection on the iDEAL page.
Note that this feature is available only with the Advanced Flow integration.

Save the shopper's Bank Identification Code (BIC)

Adyen can send the bank information used by the shopper for the iDEAL payment through the payment Authorization Webhook. To enable this, navigate to the Customer Area and configure the Webhook by enabling the "Include Bank Account Details" option under "Additional Settings."

After the iDEAL payment is completed, you will receive the Authorization Webhook. Extract the BIC number from the payload and store it for future use. You can then include it in the next iDEAL payments, indicating the BIC of the shopper's preferred bank.

Initiate the payment

To initiate an iDEAL payment using the shopper's preferred bank, invoke the Checkout /payments endpoint from your server-side application, as explained in the Advanced Flow integration. Ensure you set the issuer field with the previously stored BIC.

{
  "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
  "reference":"YOUR_ORDER_NUMBER",
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "paymentMethod":{
    "type":"ideal",
    "issuer":"BUNKNL2A"
  },
  "returnUrl":"https://your-company.com/checkout?shopperOrder=12xy.."
  }

If the shopper decides to use a different bank, make a new iDEAL payment without the "issuer" attribute and let the iDEAL page manage the bank selection.

Testing

The new iDEAL infrastructure provides an updated sandbox for testing. It's extremely important to validate your Adyen integration on our TEST environment to simulate the shopper's flow and test possible payment outcomes.

When landing on the Bank Selection page, choose the "TESTNL2A" issuer to access the test page.

Each scenario will trigger a different response that simulates the intended payment flow. Refer to the Adyen Docs Test and Go Live page to find out what response to expect.

Conclusion

The new iDEAL 2.0 significantly enhances the shopper payment experience. It also streamlines the integration process for developers who want to offer iDEAL, thanks to introducing a centralized iDEAL page, a simplified bank selection process, and iDEAL shopper profiles. To align with these changes, developers are required to update their existing integrations by April 1st, 2025.

In the Adyen TEST environment, we've made the migration to iDEAL 2.0 straightforward: simply update your existing integrations and test the new iDEAL flows.

On the LIVE platform, the configuration already supports iDEAL 2.0. Once testing is complete, merchants can seamlessly transition to the new iDEAL without additional changes.

Check out the iDEAL page and adopt the new iDEAL to offer shoppers the best experience with the most trusted payment method in the Netherlands.

Optimizing Webhook Integration: a new approach to accept events from the Adyen platform

Beppe Catanese — Thu, 02 May 2024 08:36:36 +0000

Webhooks are crucial for getting updates and notifications from the Adyen platform. Those events include confirmation about, e.g., payment authorizations, modifications of existing payments, changes in the account data, or the availability of a new report. For any developers integrating with the Adyen platform, it’s essential to receive, acknowledge, and consume this information stream and ensure their ecommerce or payment is always up to date.

Our teams also pay significant attention to keep improving the framework, ensuring reliability and performance meet the needs of our merchants and their use cases.

As part of this simplification effort, we have introduced a different way to acknowledge webhooks.

In this article… read how to accept webhooks delivered by Adyen, why we have changed the approach, the benefits, and the best practices we recommend for handling webhooks.

Accepting webhooks

The Adyen platform requires the webhook handlers to accept explicitly when a webhook is received so that Adyen can mark it as delivered.

Webhooks that are not accepted end up in the Retry Queue: Adyen will progressively try to send those events again at predefined intervals until the applications can eventually consume them.

The receiving applications must accept a webhook within 10 seconds, implementing one of the two options available.

Accept with ‘[accepted]’ response body

All integrations built with Adyen have been accepting webhooks by responding with a response body containing the string ‘[accepted]’. Applications failing to meet these specifications or taking longer than 10 seconds to do so would not successfully accept the webhook, triggering the retry process.

This approach, implemented for years, has now been revised.

Accept with any 2XX HTTP status code

The new approach simplifies the acknowledgment of webhooks.
Whether you have built a custom integration or leveraged a middleware, all webhook handlers must respond only with a successful HTTP status code (2XX). Developers can choose any 2XX status code; providing a body with the HTTP response is unnecessary.

Let’s see an example of how you can do this with NodeJS:



// webhook handler implementation

app.post("/api/webhooks/notifications", async (req, res) => {

// Notification Request JSON

  const notificationRequestItems =  req.body.notificationItems

  // fetch first (and only) NotificationRequestItem

  const notification = notificationRequestItems[0].NotificationRequestItem

// perform basic auth and HMAC validation

  authorize();

// consume event asynchronously (ie store in queue/db)

   store(notification);

// accept the event

   res.status(202).send(); // Send a 202 response with an empty body

});

Benefits and remarks

There are multiple reasons behind the change.

Align with industry standards

As webhooks have become widely used in so many platforms and applications, there have been emerging industry standards and best practices that we want to align with.

Accepting webhooks by adopting the HTTP status code 202 ("Accepted"), for example, makes clear the semantics of the interaction: the consumer has received the event and will eventually process the content.

Better support for middleware

We have seen the adoption of middleware for ingesting webhooks. Although ensuring the reliability and performance of the ingestion of events at scale, they might lack the flexibility of crafting custom response bodies.

Commercial services may also incur extra charges for delivering text within the response body, as this triggers an increased data transfer.

Remove unnecessary ambiguity

Exclusively relying on the content of the response body has presented scenarios where webhooks were successfully acknowledged even when responding with status codes in the 4XX and 5XX ranges, conventionally used to report an error.

This has resulted in false negatives, which not only affect the accuracy of performance metrics but also require additional effort to verify those cases.

New webhooks

Every newly created webhook on the Adyen platform will work with the 2XX HTTP status code option. Developers should understand how the new approach works and make sure that their implementation, either a bespoke webhook handler or the middleware, supports it by returning a successful HTTP response status code.

If the 2XX HTTP status code option isn't compatible with your integration, reach out to the Adyen Support team, and we'll assist you in finding a suitable solution.

Migrating existing webhooks

All existing webhooks, however, are not automatically updated and keep functioning as before, relying on the '[accepted]' response body. The migration is, however, straightforward and can be performed either in the Customer Area or programmatically using the Management API.

Start planning the migration of your existing webhooks now and don't miss out on the advantages highlighted above.

Update Webhook configuration in the CA

In the Customer Area, go to the "Developers->Webhooks" page and choose the webhook that is ready to be migrated. As you edit the webhook, in the "Server configuration" section, you will see the picklist "Accept webhook."

The picklist provides two choices:

With '[accepted]'
With HTTP 2XX

Change the preferred approach to "With HTTP 2XX" and confirm the choice. Note that this change is permanent and can't be reverted.

Update Webhook configuration using the Management API

The Adyen Management API allows to manage account and payment configuration programmatically. The API enables developers to perform and automate administrative tasks, configure settings and test webhooks.

In order to update the webhook configuration and change the 'accept' mechanism you can perform a PATCH request setting the acceptHttp200Confirmation property:



  
  
  example on TEST environment


PATCH https://management-test.adyen.com/v3/merchants/{merchantId}/webhooks/{webhookId}

{

   "additionalSettings": {

      "properties": {

          "acceptHttp200Confirmation": "true"

      }

   }

}

Refactor webhook handlers

Developers should also refactor the applications consuming the webhook events: provide a successful response, preferably with the HTTP status code 202, and ensure the response body is empty.

When a middleware processes the webhooks, the configuration should also be updated to adopt the new approach.

Best practices

Consuming the webhooks delivered by the Adyen platform requires understanding and adopting best practices. Let's summarize them again:

Respond with 202 and empty body

Acknowledge the webhook with an HTTP status code 202 ("Accepted") to indicate that the request has been successfully received, but the processing may not be complete.

Any successful 2XX HTTP status codes can be used. However, the recommendation is to use 202.

Returning an empty response body is also a good practice, as it keeps the response lightweight and avoids unnecessary data transfer.

Respond within 10 seconds

The webhook handler must acknowledge the webhook within a 10-second window; failure to do so will prompt Adyen to retry sending the event later.

There are a variety of reasons that can make the acceptance of the webhook longer than for 10 seconds. The affecting factors typically are the application's architecture, the complexity of the integration process, and the dependency on other systems or components.

Consider therefore adopting an asynchronous approach:

Store the event in a queue or database.
Acknowledge the webhook with a response status code 202.
Subsequently, process the event asynchronously.

This strategy allows for more efficient handling of events, ensuring smoother integration and a predictable outcome.

Security (basic auth and HMAC)

Implement the required security measures before acknowledging a webhook.

Enforce Basic Authentication (username and password) to ensure that only authorized parties can access the webhook endpoint.

Integrate Hash-based Message Authentication Code (HMAC) validation to verify the integrity and authenticity of the webhook payload before consuming it.

Monitor event logs

Use the Developer Dashboard to monitor the health of your integration. The dashboard provides insights into the webhooks activity, aggregating valuable metrics like success rate and most frequent errors.

When troubleshooting becomes necessary, dive into the Event Logs to inspect the events' status, payload, and response time.

Conclusion

The article outlines the new approach for accepting Adyen webhooks. We've compared the different methods, outlined the migration steps, and explained the rationale behind adopting any 2XX HTTP status code for webhook acknowledgment.

Now it's time to plan your migration! Follow the recommended best practices, and don't hesitate to reach out if we can help you in any way with the transition.

Developer’s Guide: working with webhooks on your localhost

Beppe Catanese — Wed, 13 Dec 2023 15:57:46 +0000

In this Developer Guide you will learn how to consume and test webhooks in your local development environment. You will also understand the different advantages and disadvantages associated with the options we recommend.

Introduction

Webhooks are an essential feature of the Adyen platform. They deliver events like payment outcome, new chargebacks, availability of a report, updates on merchant onboarding, and so on, and therefore it is important to ensure they can be received, consumed and tested during the development of your specific Adyen integration.

While inspecting the content of a webhook payload can be useful (for example by forwarding the webhook to tools like webhook.site), developers also require the capability to receive incoming webhooks directly in the application running on their laptop. It is a matter of more effective testing that verifies the correct processing on the incoming events and the associated workflow that follows.

During the development of the application there are many changes to implement and many assumptions to confirm. The flexibility of working in the local environment is therefore crucial for both developer’s experience and productivity.

This developer guide explores the following options:

Adyen Postman Collection for webhooks
Tunneling software
Using a Cloud Development Environment (CDE)

Postman Collections

Visit the AdyenDev Postman space and fork the Adyen Webhooks collection. It includes several examples of the different types of webhooks.
Each example provides the JSON payload with the event code and any other applicable field.
The HMAC signature is calculated ‘on-the-fly’ and included in the HTTP request.

HowTo

Fork the collection
Configure the environment variables:

Webhook url (default http://localhost:8080)
HMAC key (same as configured in your application)
Additional settings depending on your integration (Merchant Account for payments, Balance Platform Id for Platforms, etc..)

Send the requests to your application

When to use it

This is highly convenient in the initial development phase of the integration: developers want to quickly test the processing of the different JSON payloads that will be delivered by Adyen.

Pros ✅: easy to use with many different examples, flexible (can edit JSON payloads as needed), no need to expose a public endpoint
Cons ❌: not a real integration with Adyen backend

Tunneling Software

Tunneling software tools such as ngrok and Microsoft Dev Tunnels can be used to expose your local environment to the internet. These tools essentially create a temporary connection between your local machine and a public endpoint, hosted by the company providing the tool.

By establishing these tunnels you can:

Allow remote testing and collaboration
Run demos using your local application
Consume webhooks originated by a platform or third-party application, making webhook testing a lot simpler.

Below you can see how to test the webhook using ngrok, however the same approach applies when using a similar tool.

HowTo with ngrok

Install ngrok
Start ngrok ngrok http 8080
Copy the ngrok generated URL for https
Create/update Adyen webhook with the ngrok URL
Ensure the HMAC key for the webhook is used by the application on your localhost
Trigger a webhook: perform a payment or use Test Webhook function available in the Customer Area Note: when restarting ngrok a new URL is generated, therefore the Adyen webhook URL must also be updated. When to use it This option can be used throughout the development and testing of the integration.

Pros ✅: receive webhooks sent by Adyen platform
Cons ❌: requires exposing localhost to the Internet

Cloud Development Environment (CDE)

A Cloud Development Environment (CDE) is an online development environment that allows developers to write, test, and deploy code from a web browser. It provides developers with the necessary tools to build and test software, without setting up and maintaining a local infrastructure (tech stack and all dependencies).
As the development environment is hosted in a public cloud-based platform, it provides a convenient way to test webhooks.

There are several CDEs (Gitpod, GitHub Codespaces, Codeanywhere, etc..). Choose your preferred tool, deploy your application source code and make it reachable by Adyen.

Below you can see how to test the webhook using Gitpod (all Adyen sample applications can be deployed on Gitpod), however a similar approach applies when using a different CDE.

HowTo on Gitpod

Configure the necessary settings (API key, merchant account, HMAC key) as Gitpod environment variables
Deploy the application on Gitpod
Copy the Gitpod generated URL (note: not the Gitpod workspace URL but the URL of the web application running on Gitpod)
Create a webhook using the generated Gitpod URL as well as the path to access the webhook handler (ie https://abcd1234.gitpod.io/api/webhooks/notifications by default)
Generate the HMAC key for the webhook and copy it
In the Gitpod terminal stop the application
Set the HMAC KEY as env variable gp env ADYEN_HMAC_KEY=ASDEW##############
Update the environment variables for the terminal session eval $(gp env -e) Restart the application in the terminal (or recreate the Gitpod workpace)

When to use it

This approach might be suitable during testing and validation phases, later in the development lifecycle.

Pros ✅: receive webhooks sent by Adyen platform, source code can be tested and modified directly on Gitpod
Cons ❌: requires using cloud service, it must follow closely the “HowTo” steps (for example the Gitpod URL must be generated before configuring the webhook)

Conclusion

Webhooks are a critical component of Adyen’s platform, and testing them effectively during development is essential.

The ability to receive and process webhooks locally greatly enhances developer productivity. We’ve explored three options, each with its own advantages and limitations: Adyen Postman Collections for quick testing, tunneling software for ongoing development, and Gitpod for more comprehensive testing.

Choose the approach that fits best with your needs, requirements and development methodology, and reach out to let us know what works for you and how we can help you further.

Simplify payment testing with the Adyen Test Cards browser extension

Beppe Catanese — Mon, 27 Nov 2023 13:50:46 +0000

Testing payment flows is a challenging and time-consuming process, involving multiple steps, different payment methods, and manually entering data such as card details.

We’ve built the Adyen Test Card Chrome extension to solve this challenge, designed to simplify the testing process. By adding the extension directly to your browser, you can copy the card details to the clipboard or prefill the Adyen web Drop-in with a single click.

In this article, you’ll discover the benefits of the Adyen Test Cards extension, how we built it, and what it means in terms of security.

Meet the Adyen Test Card extension

Given the high number of returning visitors to the Adyen Test Cards page, we saw an opportunity to assist developers by streamlining the testing process. This is why we built the extension: to simplify the testing of payment flows for developers.

Designed to facilitate Adyen Checkout integration testing, the Adyen Test Card extension reduces the time and effort spent on payment flow testing. It brings the test card numbers you need directly into your browser and simplifies the testing process for developers. It removes the burden of going back and forth between different pages to collect the card data you need to test.

To make the design as simple as possible, we used chrome.sidePanel, a pre-built side panel that doesn't overlap with the tab's content and that can be easily resized or closed. The extension builds its UI and logic within the side panel, creating features that deliver user experiences that nicely blend with the Adyen Drop-in.

Make testing easy

There are multiple features that contribute to enhancing the testing experience for developers. The most significant ones are:

One-click prefill

Testing checkout integrations previously meant spending time searching for the right card, copying (from the Adyen Test Cards page or your local file) and pasting it in the right field, then repeating the same process for the expiry date and CVC data.

Now, the one-click prefill feature of the Adyen Web Drop-in does it for you. All you need to do is find the card information you need, select, and paste it in the right field.

There is also a copy-to-clipboard feature in case the card number needs to be used with applications that don't use the Adyen Web Drop-in.

Pin your favorites

You can use the ‘’Add to Favorites’’ option to speed up the testing process further. This feature makes it possible to pin frequently used cards to the top of the extension panel for quick, convenient access.

Different payment methods

Next to the different credit and debit cards, the extension also supports gift cards and IBANs. You can also submit a request to add other payment methods or card numbers.

Getting started

Installing the extension is easy and can be done in the Chrome Web Store by searching for the Adyen Test Cards extension. All you need to do is click the “Add to Chrome” button.

Watch the video on our AdyenDev YouTube channel for a detailed guide on installing and using the extension.

Security

The extension is designed with security as a key consideration, promoting best practices in payment security by discouraging using real cards for testing.

The Adyen Test Cards extension only copies (using Javascript) the selected card details into the checkout form. No other data or fields are read or changed. The source code is Open-Source, and the extension has no telemetry.

Build and Testing

Developing the Chrome extension is an easy process. You first need to create a manifest file in a JSON format that defines the extension's metadata, permissions, and assets.

In the manifest file, you can find the permissions required by the extension:

"sidePanel": Gives you access to the Chrome side-panel component.
"scripting": Allows you to execute the script to modify the page's content, specifically by populating the card details into their corresponding fields.
"activeTab": Permits you to only interact with the active tab.
"storage": Lets you save the list of favorite cards in the local storage.

Then, you need to develop the source code that contains several elements:

JavaScript and HTML code: Implements the functional behavior and rendering of the user interface.
Content script: Javascript code that manages the extension's interaction with the tab's content.
Service worker: Background script that manages the extension's state.

The Chrome extension is loaded directly from the source code during the development, leveraging the Chrome Developer mode and making code modifications immediately visible. This, combined with using Chrome DevTools, makes debugging and troubleshooting a lot easier.

Taking testing to the next level

The Adyen Test Cards Chrome extension helps developers perform more convenient, secure, and effective testing. By quickly accessing a list of test card data without manually entering the information, you can speed up the testing process and spend more time developing the integration without wasting time and energy on repetitive tasks.

Adyen Test Cards Data mimics real transactions, allowing you to test different scenarios and outcomes. By eliminating the manual entry of the payment method details, the extension reduces the possibility of error during testing, resulting in more robust integrations.

We’re proud to support developers during their integration journey with the Adyen platform. Providing effective tools removes friction, boosts productivity, and ultimately contributes to a better and more robust integration.

Get started by installing the Adyen Test Card extension from the Chrome Store or downloading it from the source code on GitHub. Give us your feedback, and let us know what you think should be included in the next releases.

Adyen for Platforms onboarding made easy

Beppe Catanese — Tue, 15 Aug 2023 09:30:34 +0000

Adyen for Platforms is our end-to-end solution designed for marketplaces and other platform models looking to set up a scalable, feature-rich platform for their merchants and end users. Amongst its vast array of features, one stands out: the Hosted Onboarding solution.

Hosted Onboarding simplifies the process for both the platform and its merchants. It reduces the complexities that come with complying to regulatory requirements and enables sellers to quickly get onboarded and accept payments.

While Hosted Onboarding offers an out-of-the box intuitive user interface, customizable themes and configuration, and tailored onboarding flows, it's important to understand there is some development work required to ensure a seamless integration.

In this article…

...discover the key benefits and functionalities of Adyen's Hosted Onboarding solution. Design an optimal flow between the platform and the Hosted Onboarding solution. Learn what developers need to consider, implement and optimize to deliver a frictionless and secure integration.

Onboarding flow

The onboarding of new sellers on the platform involves multiple steps and the process can vary significantly. The main factors that determine this process are the platform type (marketplace or platform setup), its location (countries), and the type of end merchants (individuals, organizations, sole proprietorships). Moreover when making financial products available, additional regulations may apply.

You can find a comprehensive guide of the verification process on Adyen Docs. Now we are going to focus on a specific example: get ready to onboard the restaurant Healthy Tacos for a US based platform in the food and beverage industry.

In this context the onboarding journey of Healthy Tacos looks like:

Create a profile
Fill in the required information
Provide the necessary documents (if applicable)
The Healthy Tacos account is verified and can begin accepting transactions

The diagram helps us visualize the journey on a mobile. It also distinguishes the ownership of each phase (Platform vs Adyen).

The “Setup” is the responsibility of the platform and consists of the following:

Create the “Legal Entity”
Create the “Account Holder”
Create the onboarding link

Those steps are to be implemented by the platform developers, integrating the Adyen APIs, before merchants can be involved.

Once the account is set up the “Onboarding” journey begins. This is taken care of by Adyen.

Finally the account is “Ready”. The platform must listen and process the incoming webhooks to confirm the onboarding status.

Let’s start the journey and look at what each step entails and what, as a developer, you need to design and implement.

Create a new platform

Check out the Get started guide to learn how to register for a new account as well as understanding all requirements and preliminary decisions to consider.

Prerequisites: API key and webhooks

Before starting the integration process, few prerequisites must be fulfilled.

API access

Create the API credential (and API key) for the Legal Entity Management API.

Create the API credential (and API key) for the Balance Platform Configuration API.

You will be using both APIs to create the information required to kick off the onboarding.

Tip: Check out the AdyenDev Postman space to access the Postman collections with predefined requests and JSON payloads for all Adyen APIs, including the platform and onboarding endpoints.

User role

Ensure the “Manage hosted onboarding themes” role has been assigned to your user account in the Balance Platform Customer Area.

Webhooks

Set up the webhooks to receive real-time updates from the verification process.

Webhooks play an essential role in ensuring an efficient onboarding process. You need to set up the “Configuration” webhook to always stay informed about any changes. For example, when the onboarding is completed or in case additional details must be provided.

Additionally, it is crucial to have the webhook in place after the seller is onboarded. For instance, if a new (financial) product is introduced, which mandates additional documentation, or an expired passport must be replaced, the webhook will be the mechanism to notify you about such events.

Seller account setup

Let’s tackle the first step: the account creation of the seller that must be onboarded onto the platform. This falls under the responsibility of the platform and therefore involves some development effort.

Each entity operating on the platform must have its own “Legal Entity”. This can be created using the Legal Entity Management API.

POST /legalEntities

{
   "type":"organization",
   "organization":{
      "legalName":"Healthy Tacos",
      "registeredAddress":{
         "country":"US"
      }
   }
}

which will return, if successful, the identifier of the newly created “Legal Entity” (ie LE000123).

Tip: You should consider adopting the Adyen Libraries for a robust and scalable integration. Avoid writing the REST API integration code. Instead work with your preferred tech stack and get access to pre-built functions, helpers, error handling and security features.

The next step is the creation of the “AccountHolder” linked to the “Legal Entity”. This step will be accomplished using the Balance Platform Configuration API.

POST /accountHolders

{
  "balancePlatform": "MY_PLATFORM_BP",
  "description":"Healthy Tacos account holder",
  "legalEntityId":"LE000123"
}

The seller account is now created and we are almost ready to start the onboarding. The last task is the creation of the Hosted Onboarding link.

Hosted Onboarding link

The Hosted Onboarding link is the URL that is provided to merchants who are invited to onboard onto the platform. It should be embedded into a page within your platform, for example in their “User Account” page.

It is crucial to note that the link expires after 4 minutes, therefore it should not be generated and stored to be used later. Instead, you should create the link on-demand by utilizing the LEM API's '/onboardingLinks' endpoint:

POST /legalEntities/{{id}}/onboardingLinks/

{
 “themeId” : “YOUR_THEME_ID”,
 "redirectUrl" : "https://example.com/",
 "locale" : "en-US"
}

The themeId allows you to specify a custom theme for the Hosted Onboarding experience. You can create, view and update customized onboarding themes in the Balance Platform Custom Area. A theme can have its own background image, colors and logo. The links to the Support, FAQ and Privacy pages can also be defined.

The redirectUrl property specifies the page where merchants are redirected upon completing the onboarding process. Don’t forget that they are sent to the Adyen hosted application, therefore it is very important to redirect them back to your platform at the end of the onboarding flow.

The locale property can be utilized to specify the desired language. By default, the application will use the language set in the user's browser. However, you have the option to configure the language by passing the corresponding locale, enabling customization of the link based on the market and even combining it with different themes.

Additional settings can be configured, when creating the link, to control further what the merchants can change during the onboarding.

A use case

When the platform wants to operate in Europe, it could decide to employ the language for each country (IT for Italy, NL for the Netherlands, etc.) while sharing the same custom theme (logo and branding). The platform, passing the additional settings, can also remove the possibility to edit the type and country of the “Legal Entity” which has been already set during the account setup.

Onboard your users

Once the seller account is set up and the custom theme is defined, it’s finally onboarding time!

A potential scenario involves sending an email to the sellers to access your platform, where they will find a newly generated Hosted Onboarding link. As they access the Onboarding screens, Adyen takes on the responsibility of collecting all necessary information and relevant documentation.

The happy flow

The Hosted Onboarding application will guide the merchants through a few screens:

Enter company details and decision makers
Upload or scan legitimate ID like passport or driving license
Verify the bank details
Sign the service agreement

The application is mobile-friendly and the real-time verification functionalities provide the best experience. Users can take pictures of an ID document and (where supported) choose the instant bank account verification.

To see an example of the entire hosted onboarding flow, you can watch our videos here.

In most cases the onboarding process completes smoothly. You will receive a webhook to confirm the seller is onboarded and they can start accepting payments.

Dealing with verification errors

In some cases, it may not be possible to verify all the details provided by users. Or they might be required to make modifications to the information they have submitted as well as include additional data.

The range of issues can vary, from verification errors caused by incomplete information to the rejection if a risk of fraudulent activity is detected.

When the verification is unsuccessful and the capability is denied, the webhook delivers all the information necessary to deal with it:

“allowed” false indicates the “Account Holder” cannot operate
“verificationStatus” can be invalid or rejected
“problems” listing the details of what went wrong

The payload of a webhook notifying that there is missing information (i.e. bank statement) looks like:

{
  "data": {
    "accountHolder": {
      "capabilities": {
        "sendToTransferInstrument": {
          "allowed": "false",
          "enabled": "true",
          "problems": [
            {
              "entity": {
                "id": "LE00000000000000000000001",
                "type": "LegalEntity"
              },
              "verificationErrors": [
                {
                  "code": "2_8037",
                  "message": "bankStatement was missing.",
                  "remediatingActions": [
                    {
                      "code": "1_703",
                      "message": "Upload a bank statement"
                    }
                  ],
                  "type": "dataMissing"
                }
              ]
            }
          ],
          "requested": "true",
          "verificationStatus": "invalid"
        }
      },
      "description": "Test Account holder",
      "reference": "YOUR_INTERNAL_IDENTIFIER",
      "id": "AH00000000000000000000001",
      "legalEntityId": "LE00000000000000000000001",
      "status": "Active"
    },
    "balancePlatform": "YOUR_BALANCE_PLATFORM"
  },
  "environment": "test",
  "type": "balancePlatform.accountHolder.updated"
}

You should read and process the detailed information about the error(s) and rely on the “remediatingActions” to plan the next step.

Adyen uses specific verification codes to provide the most accurate feedback. Codes are unique and never change; this should allow you to create workflows that trigger the course of action based on the verification status and corresponding code.

In the majority of cases, users will be asked to provide additional information to successfully complete the onboarding. To facilitate this, make sure to notify your users that they need to come back to the platform and continue onboarding via a newly generated onboarding link. This link will redirect the users to the application where they can provide what it is missing or incorrect.

Best practices for developers

Several aspects are very important to developers. Let’s recap the essential best practices to follow for creating a seamless onboarding process.

Webhook setup

The setup of the webhook is crucial. Make sure your application endpoint can receive and correctly handle the events that Adyen will send during and after the onboarding. Implement the necessary security measures (Basic Authentication and HMAC validation).

To learn more about webhook processing and best practices, including security, error handling, and event retries, check out the "Consuming webhooks" article on the Adyen tech blog.

Custom theme

We strongly advise creating a custom theme that seamlessly integrates with the design and style of your platform. This gives the users the feeling they are always operating within your platform, enhancing the overall user experience.

By reusing your platform's logo, images, and color schemes, you maintain a consistent branding experience and a cohesive flow between the platform and applications.

Onboarding link

Remember to generate the onboarding link on demand: create the link dynamically when the user accesses a specific page, just before starting or resuming the onboarding. Avoid storing the link permanently (as it expires after 4 minutes) and never send the onboarding link by email.

The recommended approach is to make the link available in a page that is only accessible to the user, after login. Provide a way, such as a button, for the user to generate the onboarding link. Alternatively, create one on-the-fly when the user wants to access the onboarding application.

Onboarding status

While webhook is the most effective way to stay up-to-date with the status of the onboarding, it is also possible to make a GET /accountHolders/{id} request using the LEM API endpoint. The response fetches the “Account Holder” listing all capabilities and the current verification status.

Avoid excessive and unnecessary calls to the API endpoint, instead use it only when strictly necessary. In cases where webhook processing fails or there is a requirement for real-time verification of certain information, the endpoint can be used selectively to perform these checks.

Conclusion

The Adyen for Platforms Hosted Onboarding solution offers a simple and streamlined process for platform owners to implement the onboarding of merchants, reducing complexity and ensuring compliance with regulatory requirements across markets and regions.

While the application provides out-of-the-box management of onboarding flows, an intuitive mobile-friendly user interface and customizable themes, it is important for platforms to understand there is some development work.

In this article, and through the Adyen Docs site, we advised developers to implement an effective integration that blends in with the platform branding and style. By deploying webhooks, platforms receive real-time updates, reducing the duration and effort of the entire process. By following the recommended practices, developers can deliver a solution that ensures a user-friendly end-to-end onboarding experience.

Are you ready for the next step? Visit our Adyen Developer website to discover more content and resources for developers who are building the best platforms for their users.

Effortless API Testing with the Adyen Postman collections

Beppe Catanese — Mon, 26 Jun 2023 13:52:43 +0000

As a global leading technology-driven company, at Adyen we recognise the importance of equipping developers with tools and resources that reduce time to value and make the integration with our platform faster and better.

That's why we have launched the Adyen Postman space. Leveraging the robust capabilities of Postman—a very popular tool in the API ecosystem - the developers, who work with the Adyen platform, can quickly discover, explore and test the Adyen APIs.

In this article..

…click, fork, play! Explore the benefits of using the Adyen Postman collections for discovering, exploring and testing the Adyen APIs. Checkout the step-by-step guide to getting started.

Adyen Postman Collections

Adyen Postman collections consist of preconfigured API requests that enable developers to effortlessly invoke Adyen's APIs. The collections are automatically generated from the OpenAPI specifications, ensuring all API endpoints and the JSON payloads are accurate and always up-to-date.
We provide a single workspace for all Adyen APIs. In the workspace there is a collection for each of the Adyen services, from Checkout to Recurring, Point of Sale and Platforms.

Streamlined integration

The primary advantage of adopting the Adyen Postman collections is the streamlined integration process we are able to offer. Following few simple steps the developers can perform API calls easily:

Fork the environment and define your own credentials
Fork the collection
Run the HTTP requests
Stay up to date

Fork the environment

By forking the preconfigured environment, developers obtain a template to configure essential settings such as the API key and other configuration options. It is important to keep the forked environment private to protect sensitive information.

The configuration can be defined at different levels: the preferred approach is using the Postman environment as it can be shared across collections. It is however possible to set the values in the Global scope (always available throughout the entire workspace) or in the Collection directly.

Fork the collection

To begin using the Adyen Postman collections, developers can fork a specific collection. By doing so, they can leverage the prebuilt requests, including parameters and payloads, saving valuable time and effort.
The collections are designed with flexibility in mind: they define variables that can be managed in one place and re-used across all requests (think of merchant and company accounts, platform code and other parameters).

Once the collection is forked it becomes available in the developer’s private workspace. The requests can be customized (when needed) and executed.

Developers using the Adyen Postman collections can invoke all API's endpoints using their own API key and access rights, validate the responses and verify the outcome.
The collections simplify the work of developers and testers providing many pre-defined scenarios:

make a payment using various payment methods
execute Adyen for Platforms Onboarding scenarios
issuing of physical and virtual cards
create different transaction rules
etc..

Stay Informed

The Adyen Postman space provides a convenient way to stay updated on changes and new releases. By watching a collection, users receive an email notification when there is a modification or something new in the collection.

New API releases might bring new features, corrections, or sometimes better documentation and examples. Any of those changes is pushed to the developers watching the collection allowing them to inspect the differences and pull the changes.

This proactive approach keeps developers informed about new versions and, ultimately, it is a great way to discover new features and upgrade their integration.

Payment subscriptions with Postman

Let’s see the Postman collections in action. We are going to look at the Payment Subscriptions (Tokenization) use case where the shopper authorizes a recurring payment for a subscription.

Set the API Key and Merchant Account

You start with forking the environment called “Adyen APIs”. In your own local fork, configure the X-API-Key (API Key from the API credential) and the Merchant Account. Keep the environment private as it contains sensitive information.

Fork the Checkout API collection

Next fork the Checkout API collection, then browse to the “Payments” folder and take a look at the “Tokenize card details for a subscription” request.

The request payload is pre-configured with variables like the merchantAccount (defined in the environment above), dynamic variables (i.e. auto generated reference) and some data (like the amount) that can be changed.

{
 "amount": {
  "currency": "USD",
  "value": 1000
 },
 "reference": "{{$guid}}",
 "paymentMethod": {
  "type": "scheme",
  "number": "4111111111111111",
  "expiryMonth": "03",
  "expiryYear": "2030",
  "holderName": "John Smith",
  "cvc": "737"
 },
 "shopperReference": "SHOPPER_REF_1",
 "storePaymentMethod": true,
 "shopperInteraction": "Ecommerce",
 "recurringProcessingModel": "Subscription",
 "returnUrl": "https: //your-company.com/...",
 "merchantAccount": "{{YOUR_MERCHANT_ACCOUNT}}"
}

You only need to enable the environment, in the top-right corner, and execute the request. The response body will include the resultCode ('Authorized') and the generated token (in the 'additionalData.recurring.recurringDetailReference' field).

{
 "additionalData": {
  "recurring.recurringDetailReference": "TOKEN_REF",
  "recurringProcessingModel": "Subscription",
  "paymentMethod": "visa",
  "recurring.shopperReference": "SHOPPER_REF_1"
 },
 "pspReference": "PSP00000001",
 "resultCode": "Authorised",
 "amount": {
  "currency": "USD",
  "value": 1000
 },
 "merchantReference": "111ab222-abcd-1234-aaaa-0f0f0f0f0fOf",
 "paymentMethod": {
  "brand": "visa",
  "type": "scheme"
 }
}

The last step is to make a subscription payment using the token.
Find the “Make a card payment with a token” request, set the token in the 'storedPaymentMethodId' field and execute the payment.

Adyen Postman on Github

The Adyen Postman space provides the latest and greatest version of the Adyen APIs. However it is sometimes necessary to work with an older version. This is why we also store the Postman (JSON) files for all API releases on the adyen-postman GitHub repository.
Import the JSON file in Postman and run the requests against a previous API version: test URLs, endpoint paths and payloads are already configured accordingly.

Conclusion

Adyen Postman collections provide developers with a powerful toolset for the discovery, configuration and testing of the Adyen's APIs. Using automation we ensure the collections are always up-to-date and the information is consistent. Leveraging on Postman notifications and its Git-alike version control developers are informed as soon as a new version is available.

Save valuable time and effort by avoiding manual uploads of the OpenAPI files. Instead take advantage of a readily available collection for an effortless and effective utilization.

Get started with the Adyen Postman collections. Start by forking the environment, exploring the collections and invoking the endpoints. Reduce time to value and make your integration journey simpler and better.

Adyen for Java developers

Beppe Catanese — Wed, 24 May 2023 15:00:13 +0000

In today's digital age, the ability to connect to different applications through APIs (Application Programming Interfaces) is essential for any modern platform. APIs allow the design of sophisticated workflows, enabling communication between systems that need to exchange data and provide services.

While developers can use different languages and frameworks to directly consume the REST APIs, the adoption of libraries is the most effective path to create friction-less integrations that boost both productivity and developer experience.

In a previous blog we explained the benefits of using an Adyen API Library. Let’s now explore more specifically the choices and advantages available to Java developers.

In this article..
…discover the Adyen Java Library, what’s new in the latest release, and how to bootstrap a new application or upgrade an existing one.

Adyen Java Library

The Adyen Java library is the toolkit provided to Java developers who work or will work with Adyen’s APIs. It enables them to focus on the use cases and its functional aspects while the library takes care of the necessary groundwork such as connection setup, security features (authentication, encryption and tokenization), validation, exception handling, etc…

The library includes a wrapper for each of our public APIs, complete with documentation. Whether you are implementing a payment flow, platform integration, issuing, capital or API management you only need to use this library. As you expand the scope of your integration and access new products or services, the library is already set up and the additional code is minimal.

Benefits

The Java library brings the following advantages typical of the Java ecosystem:

Easy access, available on Maven central Usage of packages to ensure encapsulation and avoid name clashing
Built-in JSON support with Gson
Custom exception class (ApiException) to provide a consistent exception handling
Dependency management: use Dependabot or Renovate to be notified when a new Adyen Java Library version is released
Comprehensive unit testing coverage: check unit tests to see an example of how services are invoked and models are defined
Built-in HTTP client (with additional proxy support) with the option to override and use your own implementation.

Supported APIs

All Adyen products are supported in the latest version of the Java library.

Online Payments: everything you need to process payments and any advanced use case: Checkout, Payouts, Recurring Payments
Point of Sale: management of point-of-sale (POS) payment terminals
Management: configuration of company and merchant accounts, stores, payment terminals
Platforms and Financial Products: work with Adyen for Platforms. Account structure, onboarding, payment flows, embedded financial services

What’s new in the Java library

The Java Library v20 upgrade delivers a lot of new features as well as several significant improvements.

A substantial redesign is perhaps the most noteworthy change, as it brings the library in line with Adyen API catalog and naming conventions. This update enables you to quickly locate the relevant Java service that corresponds to an API (i.e. CheckoutService when using the Checkout API). By maintaining consistency across Adyen documentation, the API Explorer, and code samples, you can easily find the information you need.

Another significant change is the adoption of OpenAPI-driven code generation. Java classes that map the request and response payloads are now generated using OpenAPI Generator, ensuring that the code complies with the contract (i.e. the specification), thus avoiding errors and inconsistencies.

There are other valuable improvements to make sure the library is comprehensive (all API versions are updated to the latest release, there is support for Adyen for Platforms and Embedded Financial Services), fast (providing built-in methods for JSON processing) and easy (adding adapter classes mapping each payment method).

Getting started

The Adyen Java library requires minimum setup. Make sure you match the pre-requisites (Java 11, a valid API Key), then add the dependency in your Java project with your favorite build tool.

Maven

<dependency>
  <groupId>com.adyen</groupId>
  <artifactId>adyen-java-api-library</artifactId>
  <version>20.0.0</ver

Gradle

dependencies {
  implementation 'com.adyen:adyen-java-api-library:20.0.0'
}

Setup the client that will access the Adyen service

// Setup Client and Service
Client client = new Client("Your X-API-KEY", Environment.TEST);

// PaymentsApi service
PaymentsApi paymentsApi = new PaymentsApi(client);

Use the relevant service and models to access the functionality, for example when using Checkout you can get the list available payment methods:

PaymentMethodsRequest paymentMethodsRequest = new PaymentMethodsRequest();
paymentMethodsRequest.setMerchantAccount("YOUR_MERCHANT_ACCOUNT");
PaymentMethodsResponse resp = paymentsApi.paymentMethods(paymentMethodsRequest);

// print available payment methods
resp.getPaymentMethods().stream().forEach(System.out::println);

When using the Management API (i.e. generate client Key) the approach is similar:

// Management ClientKeyMerchantLevel service
ClientKeyMerchantLevel merchantLevel = new ClientKeyMerchantLevel(client);

// generate Client Key
GenerateClientKeyResponse resp = merchantLevel.generateNewClientKey("YOUR_MERCHANT_ACCOUNT", "YOUR_API_CREDENTIAL_ID");

System.out.println(resp.getClientKey());

Working with webhooks

The Adyen Java library provides support for webhooks, an essential feature of the Adyen platform. The Java library simplifies this by providing a model for the incoming payload (NotificationRequestItem) as well as a helper class (HMACValidator) to validate the HMAC signature.

// YOUR_HMAC_KEY from the Customer Area
String hmacKey = "YOUR_HMAC_KEY";
String notificationRequestJson = "NOTIFICATION_REQUEST_JSON";
HMACValidator hmacValidator = new HMACValidator();

NotificationHandler notificationHandler = new NotificationHandler();
NotificationRequest notificationRequest = notificationHandler.handleNotificationJson(notificationRequestJson);

// fetch first (and only) NotificationRequestItem
var notificationRequestItem = notificationRequest.getNotificationItems().stream().findFirst();

if (notificationRequestItem.isPresent()) {
    // Handle the notification
    if ( hmacValidator.validateHMAC(notificationRequestItem, hmacKey) ) {
     // Process the notification based on the eventCode
 // …
    } else {
// Non valid NotificationRequest
 throw new RuntimeError("Invalid HMAC signature");
    }
}

Is your application already using the Adyen Java library? Do you want to use this latest version? Then this section is for you.

The Adyen Java Library v20 brings lots of new features but, at the same time, introduces several breaking changes. Although affecting existing working code is never good news, “breaking by design” is sometimes necessary. The redesign of the library, the code generation and many other improvements are addressing inconsistencies and removing legacy code.

The new version can better assist you in the implementation of your workflows and use cases, and allow you to easily integrate new products and features as they become available on the Adyen platform.

Migrating your code

All Java models are created based on the OpenAPI specifications, which results in various modifications such as the relocation and renaming of packages, classes, and fields.

Generic models (i.e. Address, Name, BankAccount, etc..) are no longer shared. Each package defines the models it needs. While this results in some duplication of the Java classes, it ensures a good encapsulation of the services.

Notifications have been renamed to webhooks, for example class GenericNotification is now GenericWebhook (watch out, this class includes constants that might be used by your application) and NotificationHandler has become WebhookHandler.

If you work with the Checkout API you need to consider the following changes:

The single Checkout class has been removed in favor of providing a different service class for each Checkout functionality: PaymentsApi, RecurringApi, ModificationsApi, etc.. Each service corresponds to a functionality (sub-folder) of the Checkout API (see API Explorer) ensuring consistency between the library and the API.
com.adyen.model.Amount is now com.adyen.model.checkout.Amount
com.adyen.model.checkout.details.StorePaymentMethodDetails is now com.adyen.model.checkout.StorePaymentMethodDetails
PaymentsRequest has been renamed PaymentRequest, PaymentsResponse has been renamed PaymentResponse
Several helper methods (setAmountData, setCardData, isAuthorised, getCardHolderName) have been removed to let Java models provide getter/setter methods only, consistently with the OpenAPI specification and the API Explorer documentation.

GSON

Another major change is the introduction of GSON as the preferred JSON processing framework. This should be transparent to the application as the library takes care of providing the serialization and deserialization logic that converts JSON payloads into Java objects.

You can find within each model (ie CardDetailsRequest) the methods to perform the JSON processing:

public static CardDetailsRequest fromJson(String jsonString) throws IOException {
   return JSON.getGson().fromJson(jsonString, CardDetailsRequest.class);
 }


public String toJson() {
   return JSON.getGson().toJson(this);
 }
}

In the case of handling the webhooks you can take advantage of the built-in methods, for example:

@PostMapping("/webhooks/notifications")
public ResponseEntity<String> webhooks(@RequestBody  ) throws Exception {
  // from JSON string to object
  var notificationRequest = NotificationRequest.fromJson(json);

  // consume event

Upgrade the Recurring Payment sample

Let’s look at a use case and what should be done when upgrading an existing application to the Adyen Java library v20.

On GitHub you can find a Java sample application that demonstrates how to implement payment subscriptions. It is a simplified version of a website that offers a music subscription service. There are 2 flows basically:

the shopper can purchase a subscription, saving the card details for the recurring payment (aka Tokenization)
the site administrator can make payments on behalf of the shopper (for example monthly when the subscription is renewed) and optionally expire the token

The first step is to update the dependency version in the application. It uses Gradle therefore we need to change theadyen-java-library version in build.gradle

implementation 'com.adyen:adyen-java-api-library:20.0.0'

The new version (as outlined above) has refactored packages and classes, so we need to update several imports and replace the Checkout class with PaymentsApi:

import com.adyen.model.checkout.Amount;
import com.adyen.model.checkout.CreateCheckoutSessionRequest;
import com.adyen.model.checkout.CreateCheckoutSessionResponse;
import com.adyen.service.checkout.PaymentsApi;

@RestController
@RequestMapping("/api")
public class SubscriptionResource {

// PaymentsApi service class 
private final PaymentsApi paymentsApi;
// …

Other classes and references to update:

PaymentsRequest and PaymentsResponse have been renamed to PaymentRequest and PaymentResponse: the imports and the class names must be updated
The class that defines the payment method is now called CheckoutPaymentMethod

The revised code snippet to perform a payment using a token looks like:

PaymentRequest paymentRequest = new PaymentRequest();
paymentRequest.setMerchantAccount(“YOUR_MERCHANT_ACCOUNT”);
paymentRequest.setAmount
(new Amount().currency("EUR").value(1199L));
paymentRequest.setReference(orderRef);
paymentRequest.setShopperInteraction(PaymentRequest.ShopperInteractionEnum.CONTAUTH);
paymentRequest.setShopperReference(Storage.SHOPPER_REFERENCE);
paymentRequest.setRecurringProcessingModel(PaymentRequest.RecurringProcessingModelEnum.SUBSCRIPTION);
paymentRequest.setPaymentMethod(new CheckoutPaymentMethod(new StoredPaymentMethodDetails().storedPaymentMethodId(“abc123”));

PaymentResponse response = this.paymentsApi.payments(paymentRequest);

Finally we need to update the webhook handler to take advantage of the built-in methods for deserializing the JSON payload into a Java object

// processing incoming webhooks
@PostMapping("/webhooks/notifications")
public ResponseEntity<String> webhooks(@RequestBody String json) 
throws Exception {


   // from JSON string to object
   NotificationRequest notificationRequest = NotificationRequest.fromJson(json);


// fetch first (and only) NotificationRequestItem
Optional<NotificationRequestItem> notificationRequestItem = 
notificationRequest.getNotificationItems().stream().findFirst();
if (notificationRequestItem.isPresent()) {
// consume webhooks
// ………

Next steps

It is time to get coding.

For new starters the simplest way to see the Adyen Java library in action is to look at the Java Spring sample application. The sample uses the Web Drop-in and the Java library to demonstrate the Checkout use case.

Run the application with one click using Gitpod and browse through the source code to learn how to obtain the available payment methods, perform the transaction and process the asynchronous event delivered by webhooks.

If you are upgrading an existing application the Upgrade section above will guide you through the changes and how to deal with them. We are of course ready to help you in case something is not clear or needs additional details.

We are looking forward to hearing your feedback about our libraries, what is missing or can be improved. Join our survey and let us know how we can improve them and make your developer experience better.

Building better applications with Adyen API Libraries

Beppe Catanese — Wed, 29 Mar 2023 19:11:08 +0000

REST APIs are the de-facto standard of integrating platforms and third-party services. We know that very well at Adyen since our platform is designed around modular components that can be plugged into custom workflows, interact securely with business and consumer data and integrated using open standards.

However, with the large range of available products and the many advanced use cases, the increasing complexity cannot be overlooked. That’s where API Libraries play a critical role: they simplify the integration, reduce effort and unlock the full potential of the Adyen single-platform for developers that work with us.

In this article..

…read about the features of the Adyen API Libraries, the benefits they bring and why we implement an OpenAPI-driven approach to maximize the developer experience.

Adyen API Libraries

Adyen Libraries are pre-built software components that simplify the process of accessing the Adyen REST APIs by providing a high-level abstraction. By using these libraries, developers can make API calls without having to write low-level code for the REST communication protocol, while also gaining access to functions and helpers for security, error management, and product-specific features.

The overall developer experience is enhanced significantly, making it easier and quicker to integrate with the Adyen platform.

For statically-typed programming languages (Java, .NET, Go, Typescript) the great advantage is the domain models (classes mapping the request and response payloads) that the libraries provide out-of-the-box.

The libraries, which evolve alongside the APIs, come with comprehensive documentation that explains basic setup as well as advanced settings. Additionally they include code snippets to help developers understand how to use them effectively.

Several popular programming languages and frameworks are supported.

Benefits

Developers love libraries and we are investing significant effort to make sure they are simple, fast and comprehensive:

Simple: A library provides a pre-built set of modules and functions that developers can leverage to quickly integrate the APIs. This ease of integration reduces effort by removing the need to manually build out the API integration code.
Fast: libraries includes clear documentation, code samples, and other resources that help developers understand how to use the API effectively. Default settings are coded into the library, built-in validation finds inconsistencies earlier, and exception management makes sure that errors are caught and dealt with accordingly. All of that boosts productivity and reduces time to value.
Comprehensive: A library is typically designed to work with a specific programming language and framework. Developers can therefore work with their preferred technology stack and tools, resulting in a better developer experience. Security features (HMAC validation, masking, SSL certificate management) are also part of the library to ensure that the API is used securely.

We have also chosen to open source the projects: libraries are best developed as open-source projects, with the active participation of a community that provides valuable feedback, reports issues and proposes solutions. The joint effort makes sure they deliver real value to its users.

OpenAPI driven approach

The OpenAPI specification is a pillar of Adyen’s API-first vision. We have adopted OpenAPI several years ago with the goal to create APIs that enable fast integration for developers and help businesses succeed.

Adyen’s OpenAPI specifications are generated internally and published to Github for both our users and the tools we offer. This pipeline benefits a range of applications.

The Adyen API Explorer: an interactive and comprehensive environment for working with all Adyen APIs, ensuring that developers have access to the most up-to-date documentation and functionality.

The AdyenDev Postman space: a dedicated workspace featuring the Postman collections of the latest API versions.

The Adyen Open Source Libraries: a collection of libraries, components and plug-ins that streamline the API integration process.

The Adyen Examples: the repository of all example integrations for the various libraries and plugins.

Thanks to the OpenAPI standard and the OpenAPI Generator, we’ve established a development pipeline with shorter release cycles for our libraries.

Automating libraries

Whenever a new API version is released, we publish the corresponding OpenAPI file on Github. The specifications are therefore available to the merchants and all developers who work with the Adyen platform.

The next step of our automated pipeline is to generate and update the libraries’ source code. From the OpenAPI specification files we create services, models, documentation and code snippets. The source code is reviewed, tested and merged into the existing libraries, and swiftly released.

This pipeline has allowed us to closely follow the API releases, making new features available sooner through our API libraries. It has also improved consistency and reduced mistakes by automating the code generation.

With the automation of the OpenAPI code generation we aim to have general availability across all API Libraries within 2 weeks of new releases and updates from the Adyen platform.
Vivienne Klaassens — Product Manager

Conclusion

In this article, we have discussed our approach to API Libraries and how they benefit you as a developer. By utilizing the OpenAPI standard and implementing an automated pipeline, we ensure that our libraries closely follow the API releases.

As a result, developers can quickly and easily access the latest features and capabilities of our platform, saving them valuable time and effort while they focus on their specific use cases.

We are always looking for contributors to our Open Source projects: we believe this is a great way to improve the libraries and build a stronger community. It can be code contributions, testing, documentation or even just logging an issue.

Go ahead and clone a library or a sample application, check out what works well and what else we can do to make your developer experience even better.

Reach us on our Github home or on Twitter.

Consuming webhooks

Beppe Catanese — Thu, 02 Feb 2023 11:49:05 +0000

Webhooks are an essential feature of the Adyen Platform. Payment flows often depend on external factors, like a third-party authorization. There are also events outside the control of the application that integrate with Adyen, for example triggered by customers (such as chargeback requests) or by administration functions (like the availability of a new report).

This is why we have created a sophisticated framework that caters to all those scenarios, addressing flexibility (how webhooks are set up and managed), reliability (retry and event logging), and consistency (events are delivered as they happen).

In this article..

..find out how to set up, validate, and consume webhooks. Learn about best practices for an optimal integration.

You can also check out the “Creating and consuming notification webhooks” video on our AdyenDevs YouTube channel.

What is a webhook?

A webhook is an HTTP-based push mechanism that enables Adyen to send real time events to your application. There are multiple events that might be important in your workflow, for example payment status updates and modifications or changes to the company account and store setup.

The framework allows businesses and platforms to subscribe to the events that are relevant and configure the additional data that should be delivered with the event.

An example

Let's look at a payment flow using the Adyen Drop-in: with this UI component, you can integrate a Checkout component in your web application that supports various payment methods and can perform the actual payment flow.

After the initialization (in the case of the drop-in, it is the creation of a session), the component takes care of everything, from displaying the available payment methods to capturing the data entered by the shopper and executing the payment.

What then happens is that the final payment status is later notified (confirmed) asynchronously, after a short delay, via a webhook.

Do I need a webhook?

You do. In case of a payment, the confirmation might come after a significant delay. In some local payment methods (for instance iDEAL in the Netherlands), the final outcome of the payment might take several hours to complete.

There are also a variety of events triggered by the platform that are important and which your back office (and CRM) should be informed about: we have already mentioned the availability of a new report but it is also crucial to stay up to date with changes to merchant data, updates on the terminal fleet configuration, and platform onboarding milestones.

Last but not least, the webhook framework provides features like automated retries, system notifications, and logging that help manage errors and monitor inconsistencies.

Developers in action

Let’s dig into technical details that are relevant to developers, shall we?

In the next sections we will be looking at how to:

Create and validate a webhook
Secure a webhook
Run the sample application

Create and validate a webhook

There are 2 ways to create a webhook: via the Customer Area web application and through the Management API.

In this article, we focus on the Customer Area to perform the setup (so we can better understand the relevant fields and options). You can check out our previous blog to explore how to use the Management API to automate configuration and workflows.

Customer Area

Log in to the Customer Area and access the Developers-> Webhook screen (your account must have the Merchant Technical Integrator or Merchant Admin role) and create a new webhook.

In this example, we set up a Standard notification: choose a name (Description) and enter a valid URL in the Server configuration field (this is the URL of the application that will be processing the incoming webhook event).

In this setup, we are going to use webhook.site (), a tool that helps to validate and inspect incoming webhooks without the need to expose your application or server to the internet. Grab the URL generated by webhook.site, paste it into Server configuration and click **Apply*.

(*) Other websites offer similar options

Validate the webhook

Even before creating the webhook, it is already possible to perform the validation. Click on Test Configuration and choose which Event to send: the JSON payload – which will be delivered – is displayed and can be edited (if needed).

Go ahead and test: webhook.site will show you (in real time) the incoming notification with all the relevant details (like HTTP request headers and request body) while in the Customer Area you can see the HTTP response code and body received back.

HTTP 200 but test fails

The validation however did not entirely succeed. We have received a response with HTTP status code 200 but the Customer Area warning is pretty clear: the body of the HTTP response is not what we expected.

We can address this in webhook.site: find the Edit menu where it is possible to define the body of the HTTP response. Edit the webhook configuration to return the string [accepted].
When re-running the validation we can see that the warning has disappeared and the test is now successful.

Note for developers: webhook responses must return HTTP status code 200 and a body with the string ‘[accepted]’ when this is successfully consumed.

Secure a webhook

Complete the webhook configuration, setting the recommended security settings via:

Basic Authentication
HMAC key

Note: we also recommend configuring HTTPS using TLS 1.3 for the endpoint that received the webhook events.

Basic Authentication

Setting up Basic Authentication for the webhook is very important: you want to authenticate the incoming HTTP requests and confirm they are sent by Adyen.

Define the Username and Password: those will be encoded (base64) and passed in the Authorization header. It is the responsibility of your server (or application) to verify the credentials when an incoming notification arrives.

Basic Authentication is one of the oldest and simplest ways to perform authentication over HTTP. It is supported by pretty much all web servers, API gateways, and HTTP-facing software: the recommendation is to use one of the proven products or open source packages instead of implementing this at application level.

HMAC key

Generate the HMAC key which will be used by Adyen to sign the webhook event: the signature will be included in the JSON payload and, again, it is the responsibility of your application to verify it is valid.

This security setting is also essential as it guarantees that the webhook comes from Adyen and the payload has not been altered by unauthorized parties.

Run the sample application

It is finally time to look at the code and how the webhook is consumed.

Visit the Github repository of the Adyen NodeJS sample application: it implements a Checkout screen that supports various payment methods as well as an example of the endpoint consuming the webhook.

The README file explains what you need to do to run the application on Gitpod, a developer-friendly cloud IDE (Integrated Development Environment):

Get hold of the Adyen API keys
Configure Gitpod environment variables
Launch the workspace
Configure the webhook (URL and HMAC key)

Note to developers: pay attention to the order of the steps above. Gitpod generates a new URL for each workspace. Therefore it is necessary to launch it first then copy the generated URL. Use the Gitpod URL to configure the webhook (field Server Configuration) in the Customer Area. Don’t forget to generate the HMAC key (necessary to validate the webhook payload) and store it as a Gitpod environment variable (ADYEN_HMAC_KEY).

Webhook endpoint

The Sample Application provides an implementation of the endpoint that will receive and consume the webhook event.

First take a look at the JSON payload schema to understand the structure of the payload. Here is an example with the most relevant attributes of the AUTHORISATION event:

{
  "live": "false",
   "notificationItems": [
     {
      "NotificationRequestItem": {
       "additionalData": {
         "recurring.recurringDetailReference": "123",
         "recurring.shopperReference": "xyz",
         “hmacSignature”: “ab1323…..”
       },
       "amount": {
         "currency": "EUR",
         "value": 1000
        },
        "eventCode": "AUTHORISATION",
        "eventDate": "2022-12-01T01:00:00+01:00",
        "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT",
        "merchantReference": "YOUR_MERCHANT_REFERENCE",
        "paymentMethod": "ach",
        "pspReference": "YOUR_PSP_REFERENCE",
        "operations" : [],
        "success": "true"
      }
     }
   ]
}

The payload includes an array of NotificationItems: the array will always include a single element. Developers should validate the hmacSignature and process the item.
Fortunately all our libraries include the functions to perform this type of validation, so the step is straightforward.

app.post("/api/webhooks/notifications", async (req, res) => {

 // YOUR_HMAC_KEY from the Customer Area
 const hmacKey = process.env.ADYEN_HMAC_KEY;

 // Notification Request JSON
 const body = req.body;
 const items = body.notificationItems

 // Fetch single event
 const notification = items[0].NotificationRequestItem
 console.log(eventCode: ’ + notification.eventCode);

 // validate HMAC signature
 if(validator.validateHMAC(notification, hmacKey)) {
  // process payload asynchronously
  const result =  consumePayload(notification);

  res.send('[accepted]')

 } else {
   // invalid signature
   res.status(401).send('Invalid HMAC signature');
 }
} 

function consumePayload() {
  // add to queue or DB
}

Best practices

Here are several recommendations and tips to consider for getting the best out of the webhook framework.

Security

This was already discussed above, but it is really important so let’s recap once more.

Use both Basic Authentication (authenticate incoming requests) and HMAC (validate signature of the payload). Don’t forget to leverage TLS 1.3, the most modern security protocol.

The webhook endpoint doesn’t need to include any parameter, especially your API key or other tokens. Usually a URL without query string should be enough:

https://{your_server}/{path}
Ie https://example.com/webhook/api

Manage duplicates and expect delays

It’s unusual but webhook events might be delivered more than once. Therefore you should handle duplicates in your design.

The duplicates have the same ‘eventCode’ and ‘pspReference’: use this unique combination to identify when a second event is delivered and update the information in your system accordingly. For example the Adyen Revenue Accelerate supports retrying payments that have failed but eventually become authorized after another attempt.

Webhook events are delivered with a certain delay (few seconds to minutes). We understand this is crucial in the case of payment authorizations: we strive to minimize the delay but often that depends on external factors (response from third-party systems).

Retry

Each webhook delivery expects an acknowledgement that will mark it as successful.
When this is not the case, the Adyen Platform will resend the event later. The first retry occurs after a few minutes but the following attempts (until the acknowledgement is received) are scheduled with an increasing delay.

Make sure your endpoint implementation responds correctly and monitor errors on your side.

Consume payload asynchronously

Developers might design their application logic to process the webhook events as they come, within the same application thread. For example:

app.post("/api/webhooks/notifications", async (req, res) => {

 // Notification Request JSON
 const items = req.body.notificationItems
 // Fetch single event
 const notification = items[0].NotificationRequestItem

 if( validator.validateHMAC(notification, hmacKey) ) {
   // apply business logic

  // send ack
  res.send('[accepted]')
 }

This is an approach we do not recommend. The complexity of the application logic (business rules as well as integration with other components) or the duration of certain operations (downloading large reports) might take a long time and can cause the timeout of the HTTP request.

In situations like these, the webhook event is marked as failed and will be resent later.

The best practice is to consume and process the payload asynchronously: the webhook is marked successful immediately after validating the HMAC signature while your backend takes care of consuming and processing the event.

app.post("/api/webhooks/notifications", async (req, res) => {

 if( validator.validateHMAC(notification, hmacKey) ) {
  // process payload asynchronously
  const result =  consumePayload(notification);

  res.send('[accepted]')
 } else {
   // invalid signature
   res.status(401).send('Invalid HMAC signature');
 }

}

function consumePayload() {
  // add to queue or DB
}

Conclusion

Webhooks are an essential feature of the Adyen Platform and we try our best to provide exhaustive documentation, code samples, and relevant technical content.

Does the asynchronous nature of the webhook add complexity to your architecture? Do you have suggestions or requests to improve your developer experience? Reach out to @AdyenDevs and let’s get started.

Pay by Link for developers

Beppe Catanese — Mon, 21 Nov 2022 12:46:32 +0000

Pay By Link is one the tools Adyen makes available to developers and merchants who want to support multi-channel customer journeys and implement an effective Unified Commerce strategy. They can be created online or in-store, applied to different use cases but at the same time still being part of one platform.

In this article..

.. you can read what Pay by Link is, its use cases and challenges, and how to generate one using the Adyen Customer Area, the REST APIs or the SDKs.

What Pay by Link is

Pay by Link is the generation of a unique link which can be shared with shoppers to perform a payment. It comes with three essential features: simplicity, flexibility and branding.

Start with simplicity: Pay by Link can be generated in different ways (Customer Area, APIs) and requires a minimum set of data.

The flexibility comes with the possibility to share the links in many different ways, from Social Media to messaging applications, emails or creating a QR code.

Branding is also important: the payment page can be customized (title, logo, background) by the merchant to keep the identity and style of the brand all the way to the payment execution.

What Pay by Link is not

Despite its ease of use, Pay by Link cannot replace the checkout experience.

From the shopper point of view it is important to stay within the merchant website, branded and designed to maximize the shopping experience. While Pay by Link hosted page can be customized (see above) it still represents a step outside the site where the shopper is buying the product or service, involving redirecting between different hosts and adding potential friction in the payment flow.

Pay by Link Use Cases

Pay by Link works very well in scenarios where there is no real time requirement: the shopper is not waiting for the payment outcome to be able to obtain the goods. Think, for example, of B2B payments such as invoicing.

Another valid use case is when the payment can be performed offline, for example something goes wrong during the checkout flow and the payment link is later sent to the shopper for completing the purchase.

Yet another is when shoppers interact with shop assistants via an application or a chatbot: they are guided through products and options, and eventually they receive a Pay by Link to complete the purchase.

Here is a success story on how phone orders have been made more secure with Pay by Link.

Pay by Link in the Customer Area

The easiest way to use the Pay by Link feature is to create the link in the Adyen Customer Area. This is trivial (there is no development work required for the business to accept payments) and convenient (often adopted by in-store employees or customer support teams).

Log in in the Customer Area, make sure the role “Enable Pay by Link” has been granted to your user account, then access the Create Pay by Link screen.

We do our best to make all those fields self-explanatory and provide sensible defaults. Let’s look at the most interesting ones:

“link type”: you can define if the link is single-use (only one payment can be performed) or if it is meant to be used several times, usually because it is sent to multiple recipients.
“link validity”: every link has an expiration date that can be set during the creation. Note that it is always possible, after the link is generated, to manually expire the link.

The optional “Additional Details” section can be used to ask the shopper to provide certain information before performing the payment, which is important when contact details (name, email address, delivery address) or invoicing information (name, address) are required.

Custom look-and-feel

The customisation of Adyen’s Pay by Link page is implemented by creating themes. Each theme defines the title of the page, the logo to be displayed and a background image.

Pay by Link API

Although creating Pay by Link in the Customer Area requires minimal work , developers typically need a granular control of the feature. This is why Pay by Link, like all features in the Adyen platform, provides an API.

The API allows the creation, management and integration of Pay by Link with a bespoke workflow. This can be a link following an automated process, a conversation with a chatbot or a notification on a messaging platform.

The Pay by Link REST API has a single endpoint (/paymentLinks) that supports 3 HTTP verbs: POST (create a new one), GET (retrieve existing) and PATCH (update existing). Let’s have a look.

Create a new Pay by Link (POST)

Create a new Pay by Link by performing a POST request and providing a payload with the payment attributes. Here is an example that provides the basic information, however the API allows to include additional fields (billingAddress, deliveryAddress, price and product information) when necessary.

curl -d '
{
  "amount" : {
     "currency" : "BRL",
     "value" : 10000
  },
  "countryCode" : "BR",
  "merchantAccount" : "myMerchantAccount",
  "reference" : "a121"
}
'
-H "Content-Type: application/json" 
-H "X-API-Key: #####" -X POST 
https://checkout-test.adyen.com/v69/paymentLinks

The Pay by Link creation is confirmed with the HTTP response status code 201 and a response body with the information of the newly created link (i.e. url, expiry date, etc..)

{
  "amount": {
    "currency": "BRL",
    "value": 10000
  },
  "billingAddress": {
    "city": "São Paulo",
    "country": "BR",
    "houseNumberOrName": "999",
    "postalCode": "59000060",
    "stateOrProvince": "SP",
    "street": "Roque Petroni Jr"
  },
  "countryCode": "BR",
  "expiresAt": "2022-09-21T09:48:49Z",
  "merchantAccount": "TestMerchantAccount",
  "reference": "a121",
  "reusable": false,
  "shopperEmail": "test@email.com",
  "shopperLocale": "pt_BR",
  "shopperReference": "12345678",
  "id": "XYZ123",
  "status": "active",
  "url": "https://test.adyen.link/XYZ123"
}

Working with Adyen SDKs

Adyen actively maintains several language-specific open source libraries that allow a simple and speedy integration of features and products offered by API. Using the SDK developers can create the Pay by Link from the environment and technology stack of their choice.

When using the Java SDK in a Kotlin application, for instance, developers only need to initialize the Client handler and call the corresponding PaymentLinks create method.

// obtain client
private var client = Client(“#####”, Environment.TEST)
private var paymentLinks = PaymentLinks(client)

// create new Pay by Link
val createPaymentLinkRequest = CreatePaymentLinkRequest()
   .amount(
       Amount()
           .currency("BRL")
           .value(10000)
   )
   .merchantAccount(adyenConfig.merchantAccount)
   .reference(reference)
   .countryCode("BR")
   .billingAddress(
       Address()
           .street("Roque Petroni Jr")
           .postalCode("59000060")
           .city("São Paulo")
           .country("BR")
   )

val paymentLink = paymentLinks.create(createPaymentLinkRequest)

Get and Patch

The Pay by Link API also provides a way to access (GET) the information about an existing Pay by Link as well as the option to update (PATCH) the status. The latter is interesting, for example, when the Pay by Link needs to be manually expired.

{
  "status": "expired"
}
' 
-H "Content-Type: application/json" 
-H "X-API-Key: #####" -X PATCH 
https://checkout-test.adyen.com/v69/paymentLinks/XYZ123

This again can be done using the SDK.

// obtain client
private var client = Client(“#####”, Environment.TEST)
private var paymentLinks = PaymentLinks(client)

// get paymentLink by id
var paymentLink = paymentLinks.retrieve(“00000001”)

// update paymentLink status
paymentLink = paymentLinks.update("000000001", 
UpdatePaymentLinkRequest().status(
  UpdatePaymentLinkRequest.StatusEnum.EXPIRED)
)

It must be noted that the GET endpoint returns the status of the payment link and not the payment status.

Working sample

The best way to demonstrate the Pay by Link capabilities to the developers is of course to create a working demo. This is why we have developed a Kotlin Sample application on Github.

The sample application demonstrates how you can create payment links and perform (simulate) the actual payment as well as check their status. It is developed with a Kotlin backend, a NodeJS frontend and it can be deployed on Gitpod.

The Pay by Link capabilities are integrated using the open source Adyen Java API.

Feel free to clone the source code, play around and provide us with some feedback or requests to improve it further.

Interesting to know

Unlike the Customer Area the Pay by Link API supports all payment methods available to the merchant. There are few payments where extra information is required, for example indicating price and product information as lineItems: that can only be done via the API.

Moreover the links created via API can optionally store the payment details, something not supported in the CA for security reasons.

Challenges

Although Pay by Link is easy and flexible, it is not intended to replace the shopper checkout experience. It might be tempting to adopt this tool outside its scope, but developers should remember the friction of redirecting shoppers to different pages. From a technical point of view the complexity of dealing with different entry points (start of the checkout, redirect back from the payment page).

It is also important to remember that Pay by Link based solutions should anyway integrate webhooks. Notification webhooks deliver the final outcome of the payment and must be consumed to verify the transaction is successful and the purchase can be confirmed.

Conclusion

Pay by Link remains a powerful tool when used within the right context. Merchants and developers should ensure Pay by Link is adopted for the right use case. In that case the creation of simple yet robust payment flows can bring significant competitive advantages with a small development effort.