DEV Community: Adyen

Building a GlobalStream: Replication Challenges and Optimizations

Ayodeji Ogundare — Fri, 10 Oct 2025 10:50:13 +0000

By Gaurav Singh & Luciano Sabença, Streaming Platform Team

Global data streaming requires careful tradeoffs between performance, compliance, and reliability. At Adyen, replication is essential: data must remain close to producers to reduce latency and meet regulations, while also being centralized for analytics.

In this blog, we share our experience optimizing MirrorMaker 2 for large-scale, cross-continent Kafka replication, the parameter tuning we applied, and the hidden behaviors in Kafka Connect that ultimately unlocked the required throughput.

Why Replicate?

There are many things you need to take into account when designing a data streaming platform for a company such as Adyen. One of the most important aspects of it is data location and replication. Due to performance, reliability, and compliance, keeping data close to producers is usually a good idea. After all, you don't want to wait in line at the cashier to confirm the payment for that fat burger you just bought on that nice beach in Australia while your payment was being sent to Europe. However, it's also a common practice to have all data in a centralized cluster(s) in centralized locations for analytical purposes. These two need a bridge, which is where mirroring comes in.

Mirror Maker

When it comes to copying data between Kafka clusters, Mirror Maker is the default open source tool. MirrorMaker 2 is the current version, and it's built on top of Kafka Connect, a platform designed to make it easier to integrate Kafka with other tools such as databases and distributed file systems, and - why not? - another Kafka cluster. Setting up Mirror Maker is fairly straightforward, but tuning it to the performance Adyen requires isn't. Let's go over the journey into the depths of Kafka Connect and parameter tuning to find a solution!

Playing the Volume Game

Kafka is a highly flexible tool and serves as the backbone for many different architectural patterns. It can be used for batch processing, real time processing, or any combination of these two extremes. With default parameters, Kafka producers and consumers are optimized for low-latency use cases: batch sizes are not large, and records are sent immediately to the server (i.e., linger.ms = 0). Given that our volume is on the order of several hundred thousand messages per second, any optimization has a huge impact on replication latency. In our case, the default settings were not good enough to keep the latency bounded within a few seconds; in fact, our replication latency was on the order of minutes. Since we are transferring this data across continents, we don't expect very low latency for replication, but such high latency indicates that we were at the maximum possible throughput for this configuration, so we needed to revisit those parameters.

We made the following adjustments on the producer side of MirrorMaker:

batch.size: Increased from the default 16384 to 409600. This leads to larger batches per request, and less requests to replicate the same number of messages
linger.ms: Increased from 0 to 200. This parameter sets how long the Kafka driver can wait before dispatching the messages. 0 means send immediately. Giving more time to the driver allows it to batch more messages in the same batch.
compression.type: Changed from 'none' to 'zstd'. Activating compression means more messages per batch.
These changes didn't yield the desired results. There was another bottleneck. We then turned our attention to the consumer parameters. After all, MirrorMaker is both a consumer from the source cluster and a producer to the destination.

We adjusted:

fetch.min.bytes: Increased from 1 to 5000. So we wait a bit more to ensure that more data is available for consumption, thus decreasing the number of consumer requests and optimizing throughput.
max.fetch.records: Increased from 500 to 2000 with the objective of fetching more records per requests and sending more requests to the producer.

The goal here was clear: have the consumers fetch as much data as possible at once and send it in very large batches to the destination cluster. The idea is to optimize network traffic and amortize large distance latencies when measured per unit of replicated byte.

Despite these efforts, the throughput remained stubbornly the same. Each time we restarted with new parameters, the record rate would spike briefly before settling back to its previous baseline, indicating that our changes were not having a lasting impact. This led us to believe there was a deeper, underlying issue we were missing.

The Missing Piece

There was, however, a missing piece of the puzzle to make it work as we expect: how Kafka Connect changes are persisted and saved to the nodes. As we mentioned before, MM2 is built on top of Kafka Connect. Kafka Connect uses some internal Kafka topics to store and persist its state and configuration. This gives us three possible layers of configuration:

Kafka driver's parameters
Mirrormaker configuration
Internal Kafka Connect state

We needed to be sure that whenever any configuration was changed in any of these three places it would be reflected in the others. It soon became clear that this wasn't really the case: whilst our MM2 consumer was able to consume a quite decent amount of data, the producer wasn't really able to keep the throughput high and wasn't creating big enough batches for our use-case.

After digging a bit into the internal configuration topics and on MM docs, we understood the root cause: configuration changes on the connectors are not updated while any instance of the connector is up and running. Instead, they are read from the internal mm configuration topics and applied to the connectors. This was our case: we are running MM2 in distributed mode, so we didn't stop all nodes and start them again. Although the behaviour makes sense, it prioritizes consistency when the application is running; it's not a very intuitive behavior and it almost led us to explore weird paths in our search for better throughput.

The Results: A Tale of Two Graphs

The results were dramatic once we understood the necessity of a complete restart. As seen in the graph below, the number of records per request skyrocketed. We were also able to validate via logs and via the data in the topic that the parameters being used by the producers and consumers were the same as we originally intended.

As a consequence of those parameters, the total number of requests sent by the producer dropped significantly and each request now was able to replicate more messages.

This experience was a valuable lesson in the intricacies of managing a distributed system like Kafka Connect. Understanding the operational details of how configurations are managed was the key to unlocking the needed performance. This journey highlights that sometimes the most significant gains come not from simply tweaking parameters, but from a deeper understanding of the tools themselves.

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.

A Guide to Integrating with Adyen Web for 3D Secure 2 Payments

Sarah 🦄 — Fri, 12 Jan 2024 14:36:30 +0000

The goal of this guide is to provide the necessary context and examples to empower developers to handle 3D Secure 2 payments with the Adyen Web solution for the browser. This guide has a companion demo application with code examples for each flow which can be found in our github examples.

What is 3D Secure 2?

3 Domain Secure (3DS) is a security measure for online payments. The 3 domains (acquirer, scheme, and issuer) interact with each other using a 3DS protocol where they exchange information, providing an authentication mechanism for the consumer during a transaction.

3D Secure helps prevent fraud and is available for Card Not Present (CNP) transactions with all major card networks, and is mandatory in the EU, following the Revised Payment Services Directive (PSD2). For more in depth details about PSD2 and SCA you can refer to our documentation.

When facilitating a card payment online we want to do all we can to ensure the shopper is who they say they are. This way we reduce fraudulent transactions and improve authorisation rates for real shoppers.

There are two different ways customers can verify themselves using 3D Secure: frictionless and challenge. The frictionless flow is based on background information that doesn't require the customer to actively verify themselves. The challenge flow means the issuer has determined the transaction needs additional verification from the customer. For example; the shopper may have to enter a passcode they receive on their phone. The more information about the shopper we send in the payment request the higher the chances of a frictionless flow.

How to support 3DS2 transactions with Adyen

Our Adyen Web SDK and server libraries support two options for 3DS2 payments:

Native

The authentication experience occurs on your merchant page. Our SDK renders the necessary components and communicates directly with the ACS. The shopper never leaves your page.

Redirect

The authentication experience occurs on an Adyen page. Our SDK will redirect the shopper to an Adyen domain. The shopper is then redirected back to your merchant page once the authentication is complete.

Both Native and Redirect flows can be either frictionless or challenged. Which option to choose depends on a multitude of factors and is out of scope for this guide. For more in depth information about each flow you can refer to our documentation. This guide will show you how to integrate for both flows.

Comparing Adyen Solutions

When choosing a solution with Adyen you have a couple of choices to make; on the client side you can choose to integrate with our Drop-in or our Components. On the server side you can choose to integrate with our Sessions flow or our Advanced flow. This tutorial will demonstrate the Drop-in, you can follow along with our Github example.

Drop-in vs. Components

Drop-in is our pre-built UI for accepting payments. We recommend Drop-in as it renders a full list of available payment methods and does a lot of the heavy lifting for you. It also has 3D Secure 2 support built-in.

Components are our customizable UI components which render individual payment methods. Choose Components if you prefer to compose your own UI.

Both Drop-in and Components are available from our Adyen Web SDK.

Sessions flow vs. Advanced flow

The Sessions flow consists of one API call that creates a payment session which is used by the Adyen Web SDK to facilitate the payment flow. The advantage is that with the Sessions flow you don’t have to do any extra work for 3DS2, everything is handled by the Drop-in/components. However, it’s important to note that the Sessions flow does not support 3DS2 redirect flow so if you wish to use redirect then you need to use the Advanced flow.

The Advanced flow consists of three API calls: /paymentMethods, /payments and /payments/details. You will need to configure and support each of these API calls in the advanced flow to facilitate the payment. Luckily you can use one of our Adyen server libraries to make this a lot easier.

When integrating with Adyen you can break it down to three core parts; the server, the client and the webhook.

Server: Handle the payment request(s) on your server using one of our API flows.
Client: Show the payment on your web page using our pre-built Drop-in or composing your own UI with our Components.
Webhook: Configure and receive webhook notifications with the outcome of each payment. Webhooks are out of scope for this guide.

How 3DS2 is applied is dependent on your Dynamic 3DS rules. For more information on this please refer to our documentation.

Integrate with Sessions Flow

This guide assumes you already have your Adyen API key and client key and are pointing to our TEST environment. If you haven’t you can find directions here.

Let’s start with configuring the Sessions flow on our backend. The Sessions flow consists of one API call /sessions.

Install Adyen API library

The first step is to install the Adyen API library, these examples will be in TypeScript so we’re going to use the Node.js library. These examples are built using version 15.1.0 of the api-library which utilizes the latest version of Checkout API (71).

If you have npm installed, you install the library in your app by running:

npm install --save @adyen/api-library
npm update @adyen/api-library

Configure CheckoutAPI

Now we have the library installed, let’s write our payment service. The first step is to initialize the Client object with your API key and environment, then we need to pass this client into the CheckoutAPI constructor to initialize our CheckoutAPI object.

// ../backend/../payments.ts

import { Client, CheckoutAPI } from '@adyen/api-library';

// initialise the client object
 const client = new Client({
      apiKey: 'YOUR_API_KEY_HERE',
      environment: 'TEST',
 });

 // intialise the API object with the client object
 const paymentsAPI = new CheckoutAPI(client).PaymentsApi;

The CheckoutAPI object exposes a few different API helpers, we want to use the PaymentsApi. Now we have initialized checkout, we can use it to call the sessions API.

Handle /sessions on the server

First we create an asynchronous function to submit the sessions request. We build our request object with all of the fields we want to pass to our API. In the example below we include the fields we recommend to increase the chances of a frictionless flow.

// ../backend/../payments.ts

async postForSessions(data): Promise<CreateCheckoutSessionResponse> {
 const sessionsRequestData: CreateCheckoutSessionRequest = {
      amount: {
        currency: "EUR",
        value: 1000, 
      },
      countryCode: "NL",
      shopperName: {
        firstName: "FirstName",
        lastName: "LastName",
      },
      telephoneNumber: "0612345678",
      billingAddress: {
        houseNumberOrName: "1",
        street: "Shopper Billing Street",
        city: "Amsterdam",
        country: "NL",
        postalCode: "1234AB",
      },
      deliveryAddress: {
        houseNumberOrName: "1",
        street: "Shopper Delivery Street",
        city: "Amsterdam",
        country: "NL",
        postalCode: "1234AB",
      },
      shopperIP: "shopperIP",
      shopperEmail: "shopperEmail",
      channel: PaymentRequest.ChannelEnum.Web,
      reference: "YOUR_PAYMENT_REFERENCE",
      returnUrl: "https://your-company.com/checkout?shopperOrder=12xy..",
      merchantAccount: "YOUR_MERCHANT_ACCOUNT",
 };

 const sessionsResponse = await this.paymentsAPI.sessions(sessionsRequestData);
 return sessionsResponse;
}

Above we pass the request data to the sessions function on the paymentsAPI object and return the awaited response.

We have now set up our backend for the sessions flow. Let’s review what we did:
✅ We installed the Adyen API library
✅ We configured the Client object with our API key and environment
✅ We instantiated the CheckoutAPI with our Client object and called the PaymentsAPI
✅ We created a function to handle the /sessions API call

Now let’s set up our frontend to send the request.

Install Adyen Web SDK

In our frontend app we will use the Adyen Web SDK so let’s install it by running the command below. These examples are using version 5.55.1.

npm install @adyen/adyen-web --save

To make sure our Drop-in looks as expected we need to import the Adyen web stylesheet in our app. This might look different depending on your set up. Here we will import it in our index.js file. You can override the styling rules to add your own styles. We also import the AdyenCheckout module so we can use it later to create our checkout instance.

// ../frontend../dropin.js

import AdyenCheckout from "@adyen/adyen-web";
import "@adyen/adyen-web/dist/adyen.css";

Configuring the Web Drop-in

Since we are using session flow our Drop-in requires the response from the sessions API call in its configuration. So let’s first make a call to our backend to receive the response from the /sessions endpoint.

//  ../frontend../dropin.js 

const sessionsRequest = {
// data for your request object, may include shopper details, the amount etc...  
}

const sessionsResponse = await postDoSessions(sessionsRequest);

// ../frontend../payments.js

export const postDoSessions = async (data) => {
// send the sessions request to your backend  
const response = await fetch("/api/sessions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ data }),
  });
  return await response.json();

};

Now we have the sessions response we can now build our configuration object and create our checkout instance.

// ../frontend../dropin.js 

// create configuration object to pass into AdyenCheckout
const checkoutConfig = {
    locale: "en_US",
    environment: "test",
    clientKey: YOUR_ADYEN_CLIENT_KEY,
    session: sessionsResponse, // response from the /sessions call 
    onPaymentCompleted: onPaymentCompleted,
    onError: onError,
};

Our configuration object has two events which handle the payment:
onPaymentCompleted is triggered once the payment completes, here you can handle what should happen afterwards.
onError is triggered if an error is thrown. Use this event to gracefully handle errors for your shoppers.

We create callback functions for each which will be executed when the events are invoked by the Drop-in.

// ../frontend../dropin.js

  const onPaymentCompleted = (result, dropin) => {
    // handle payment completed here
  };

  const onError = (error, dropin) => {
    // handle error here
  };

For a full list of all configuration options you can refer to our documentation.

Now we have our configuration object set up with our session data, let's instantiate the Drop-in, pass the configuration to AdyenCheckout and mount the instance as follows:

// ../frontend../dropin.js

const checkout = await AdyenCheckout(checkoutConfig);

// This will mount the checkout component to `<div id="dropin-container"></div>`
checkout.create("dropin").mount("#dropin-container");

The component will be mounted to an element with an id of #dropin-container. For our last step let’s add a div element to our HTML with this id.

// ../frontend../dropin.html

<div id="dropin-container"></div>

Now we’ve set up our frontend to handle payments with Sessions flow and Drop-in. Let’s review what we just did:
✅ We installed the Adyen Web SDK
✅ We called our sessions API session data.
✅ We created our configuration object passing the sessions response object and creating callback functions to handle the events.
✅ We instantiated our checkout object with our config.
✅ We created and mounted our Drop-in to our DOM.

Integrate with Advanced Flow

This guide assumes you already have your Adyen API key and client key and are pointing to our TEST environment. If you haven’t you can find directions here.

Let’s start with configuring the advanced flow on our backend. The advanced flow consists of three API calls /paymentMethods, /payments and /payments/details.

Install Adyen API library

If you have npm installed, you install the library in your app by running:

npm install --save @adyen/api-library
npm update @adyen/api-library

Configure CheckoutAPI

// ../backend/../payments.ts

import { Client, CheckoutAPI } from '@adyen/api-library';

// initialise the client object
 const client = new Client({
   apiKey: 'YOUR_API_KEY_HERE',
   environment: 'TEST',
});

// intialise the API object with the client object
const paymentsAPI = new CheckoutAPI(client).PaymentsApi;

The CheckoutAPI object exposes a few different API helpers, we want to use the PaymentsApi.

The advanced flow consists of three API calls, let’s create functions to handle each of these requests.

Handle /paymentMethods on the server

The initial /paymentMethods call is used to get a list of the available payment methods. We need to pass the response of this call to our Drop-in configuration. Which payment methods are returned depends on your merchant configuration. We build our request object with the fields we want to pass to the API. For this example we will just use the required field of merchantAccount. You can find the optional parameters here.

// ../backend/../payments.ts 

async postForPaymentMethods(): Promise<PaymentMethodsResponse> {
    const postData = {
      merchantAccount: 'YOUR_MERCHANT_ACCOUNT',
    };

    const paymentMethodsResponse: PaymentMethodsResponse = await     this.paymentsAPI.paymentMethods(postData);

    return paymentMethodsResponse;
  }

Handle /payments on the server

The /payments request sends the data related to the payment and the shopper. We want to call this when our shopper submits on the Drop-in. Our payments request may look different depending on whether we want to implement the native flow or the redirect flow.

Payment request for Native flow:

If we want to implement the native flow then we need to set the threeDSRequestData object in the AuthenticationData object of the API request like so:

// ../backend/../payments.ts

const authenticationData: AuthenticationData = {
      threeDSRequestData: {
        nativeThreeDS: ThreeDSRequestData.NativeThreeDSEnum.Preferred, 
      },
};

Here we have set nativeThreeDS to be preferred, this will ensure we get the native flow. You can find the other optional parameters here.

Now let’s build the rest of our request object and make the payments request. In the example below we include the fields we recommend to increase the chances of a frictionless flow.

// ../backend/../payments.ts

async postForPaymentsNative(data): Promise<PaymentResponse> {

    const paymentRequestData: PaymentRequest = {
      amount: {
        currency: "EUR",
        value: 1000,
      },
      authenticationData: {
        ...authenticationData, // pass our authenticationData object 
      },
      countryCode: "NL",
      shopperName: {
        firstName: "FirstName",
        lastName: "LastName",
      },
   telephoneNumber: "0612345678",
   billingAddress: {
     houseNumberOrName: "1",
     street: "Shopper Billing Street",
     city: "Amsterdam",
     country: "NL",
     postalCode: "1234AB",
   },
   deliveryAddress: {
      houseNumberOrName: "1",
      street: "Shopper Delivery Street",
      city: "Amsterdam",
      country: "NL",
      postalCode: "1234AB",
   },
      shopperIP: "ShopperIP",
      shopperEmail: "ShopperEmail",
      channel: PaymentRequest.ChannelEnum.Web,
      browserInfo: data.browserInfo, 
      origin: url, 
      paymentMethod: data.paymentMethod, 
   reference: "YOUR_PAYMENT_REFERENCE",
   returnUrl: "https://your-company.com/checkout?shopperOrder=12xy..",
   merchantAccount: "YOUR_MERCHANT_ACCOUNT",
    };

 const paymentResponse: PaymentResponse = await this.paymentsAPI.payments(paymentRequestData);

    return paymentResponse;
  }

Above we pass the request data to the payments function on the paymentsAPI object and return the awaited response.

Payment request for Redirect

Since redirect is the default in advanced flow we don’t need to pass any additional data to our authenticationData object in our payments request.

We can just build our request object and make the payment request. In the example below we include the fields we recommend to increase the chances of a frictionless flow.

// ../backend/../payments.ts

async postForPaymentsRedirect(data): Promise<PaymentResponse> {

    const paymentRequestData: PaymentRequest = {
      amount: {
        currency: "EUR",
        value: 1000,
      },
     countryCode: "NL",
      shopperName: {
        firstName: "FirstName",
        lastName: "LastName",
      },
   telephoneNumber: "0612345678",
   billingAddress: {
     houseNumberOrName: "1",
     street: "Shopper Billing Street",
     city: "Amsterdam",
     country: "NL",
     postalCode: "1234AB",
   },
   deliveryAddress: {
      houseNumberOrName: "1",
      street: "Shopper Delivery Street",
      city: "Amsterdam",
      country: "NL",
      postalCode: "1234AB",
   },
      shopperIP: "ShopperIP",
      shopperEmail: "ShopperEmail",
      channel: PaymentRequest.ChannelEnum.Web,
      browserInfo: data.browserInfo, 
      origin: url, 
      paymentMethod: data.paymentMethod, 
   reference: "YOUR_PAYMENT_REFERENCE",
   returnUrl: "https://your-company.com/checkout?shopperOrder=12xy..",
   merchantAccount: "YOUR_MERCHANT_ACCOUNT",
    };

    const paymentResponse: PaymentResponse = await this.paymentsAPI.payments(paymentRequestData);

    return paymentResponse;
  }

Handling PaymentMethod and BrowserInfo

In both native and redirect examples you may notice we set paymentMethod and browserInfo with the data object passed from the client. This data comes from the Drop-in state and is returned in the onSubmit event callback that we will define later.

Handle /payments/details on the server

The /payments/details request returns the details of the payment request we made. This response will include the result of the Authentication. What we pass to the details call is different depending on native or redirect flow, we will delve into this in the upcoming client section. For now we can create our request like so:

// ../backend/../payments.ts

 async postForPaymentDetails({ details }: { details: PaymentCompletionDetails }): Promise<PaymentDetailsResponse> {
    const paymentDetailsResponse: PaymentDetailsResponse = await this.paymentsAPI.paymentsDetails({ details });

    return paymentDetailsResponse;
  }

We have now set up our backend for the advanced flow. Let’s review what we did:
✅ We installed the Adyen API library
✅ We configured the Client object with our API key and environment
✅ We instantiated the CheckoutAPI with our Client object and called the PaymentsAPI
✅ We created a function to handle the /paymentMethods API call
✅ We created a function to handle the /payments API call
✅ We created a function to handle the /payments/details API call

Now let’s set up our frontend to send the request.

Install Adyen Web SDK

In our frontend app we will use the Adyen Web SDK so let’s install it by running the following command:

npm install @adyen/adyen-web --save

To make sure our Drop-in looks as expected we need to import the Adyen web stylesheet in our app. This might look different depending on your set up. Here we will import it in our index.js file. You can override the styling rules to add your own styles. We also import the AdyenCheckout module that we will use later to create our checkout instance.

// ../frontend/../dropin.js

import AdyenCheckout from "@adyen/adyen-web";
import "@adyen/adyen-web/dist/adyen.css";

Configuring the Web Drop-in

Since we are using advanced flow the first thing our client needs is the paymentMethods response from the /paymentMethods API so we can configure the drop-in.

// ../frontend/../dropin.js

 const paymentMethods = await getPaymentMethods();

// create configuration object to pass into AdyenCheckout
const checkoutConfig = {
      paymentMethodsResponse: paymentMethods,
      locale: "en_US",
      environment: "test",
      clientKey: CLIENT_KEY,
      onSubmit: onSubmit,
      onAdditionalDetails: onAdditionalDetails,
 };

Our configuration object has two events which handle the payment. We create callback functions for each which will be executed when the events are invoked by the Drop-in.

The onSubmit function is triggered when the shopper clicks the Pay button, here you can send the payment request and handle the response actions.

// ../frontend/../dropin.js

const onSubmit = async (state, dropinComponent) => {
  if (state.isValid) {
     const paymentResponse = await postDoPayment(state.data);
     // check result code and handle action here if required  
     if (paymentResponse.resultCode === "Authorised") {
        // no threeDS required
     } else if(paymentResponse.action) {
       dropinComponent.handleAction(paymentResponse.action);    
     }
  }
};

In the code example above you can see we first check the state is valid to ensure there are no errors in the input and then pass the state.data to our payment request. This is the object that has the data for paymentMethod and browserInfo which we set in our API request. We await the payment response, the response will have a resultCode and depending on that resultCode it could also have an action object. An action is an additional step required which can be handled by the Drop-in handleAction method. Once we receive the response we check the resultCode and check if there is an action. Since we are building for 3DS2 we know we can expect an action of either redirect or threeDS2 (for native). For more information on actions you can go refer to our documentation.

The onAdditionalDetails function is triggered if a payment method requires additional details. In our context this event will be invoked to handle the native 3DS2 result.

// ../frontend/../dropin.js

 const onAdditionalDetails = async (state, dropinComponent) => {
      const paymentDetailsResponse = await postDoPaymentDetails(state.data);
      // handle result 
    };

When integrating with the 3DS2 native flow we use the onAdditionalDetails event callback to submit the /payments/details API call and get the final result. The onAddtionalDetails event is automatically triggered in native flow by the Drop-in once the shopper has completed the 3DS2 action.

For a full list of all configuration options you can refer to our documentation. Now we have built our configuration object and handlers for the callbacks, let’s instantiate the drop-in, pass the configuration to AdyenCheckout and mount the instance as follows:

// ../frontend../dropin.js

const checkout = await AdyenCheckout(checkoutConfig);

// This will mount the checkout component to `<div id="dropin-container"></div>`
checkout.create("dropin").mount("#dropin-container");

The component will be mounted to an element with an id of #dropin-container. For our last step let’s add a div element to our HTML with this id.

// frontend/../dropin.html

<div id="dropin-container"></div>

Handling the 3DS2 result

We mentioned above that the onAdditionalDetails callback is automatically triggered for native 3DS2. Here you will get the details result in the state.data object which is the first parameter of the callback event. Pass this data to the /payments/details API to complete the 3DS2 transaction.

If the integration is for 3DS2 redirect then we need to handle the redirect result differently. In a redirect flow when the shopper is redirected back to your merchant page the returnUrl will have the redirectResult appended, it might look something like this:

https://your-company.com/checkout?shopperOrder=12xy&redirectResult=X6XtfGC3%21Y...

In this case we need to parse the url to get the redirectResult and then pass this to our /payments/details call.

// ../frontend/../dropin.js

// example of how to parse redirect result from the url 
const parseRedirectResultToRequestData = (url) => {
    const redirectResult = url.substring(url.indexOf("=") + 1, url.length);
  return {
    details: { redirectResult },
  };
};

const requestData = parseRedirectResultToRequestData(url);
const paymentDetailsResponse = await postDoPaymentDetails(requestData);

And that’s it, now we’ve set up our frontend to handle payments with advanced flow and Drop-in. Let’s review what we just did:
✅ We installed the Adyen Web SDK
✅ We called our paymentMethods API to get the paymentMethods data
✅ We created our configuration object passing the paymentMethods data and creating callback functions to handle the events.
✅ We instantiated our checkout object with our configuration.
✅ We created and mounted our Adyen Drop-in in our DOM.
✅ We handle the 3DS2 result in our onAdditionalDetails event callback in the native flow
✅ We handle the 3DS2 result by parsing the redirectResult from the url in the redirect flow

Mobile integrations

This guide was intended for a browser flow of 3DS2 with Adyen Web. If you wish to integrate with 3DS2 for mobile we highly recommend using one of our dedicated mobile SDKs available for Android or iOS. If you still prefer to use a web integration then we strongly recommend using the redirect flow over native flow.

Conclusion

Thanks for reading! In this blog we’ve covered:
✅ What is 3D Secure 2
✅ How Adyen supports 3DS2 transactions
✅ A comparison between the different integration options
✅ How to integrate using the Sessions flow
✅ How to integrate using the Advanced flow
✅ How to handle 3DS2 on the client-side using Adyen Drop-in

We hope you find this technical blog helpful. Don’t forget to check out the github repository which contains a fully working integration-example. It’s important to note that, while this guide promotes an ideal flow with our recommended best practices, all payment flows are uniquely complicated, so if this guide doesn’t exactly suit your needs, you can refer to our extensive documentation guides.

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.

Sweeps on the Adyen Balance Platform for Developers

Kwok He Chu — Mon, 20 Nov 2023 15:18:06 +0000

TL;DR In this blog post, we show you how you can configure sweeps to automate payouts to your user's verified bank accounts. We’ll explain the different types of sweeps, outline the scenarios they are designed for, and explain the process of setting up sweeps through either the Customer Area or using APIs.

Adyen for Platforms offers a comprehensive solution tailored for marketplaces that aim to deliver a flexible, robust and fully-featured platform to support their merchants and end users on a large scale. The core of every successful platform is the unique relationship built over time between the platform and its customers. Merchants process a vast number of complex transactions everyday, with different attributes and configurations, like currency, payment methods, split amounts and fees. They also need easy access to their funds, making fast and reliable payouts an indispensable tool of the platform.

In this blog, we’ll answer the following questions:

What are sweeps?
What types of sweeps exist and their use cases.
How to configure sweeps.

What are sweeps?

Let’s start with an example. Jan runs a very successful marketplace that allows users to buy and sell their cars in Amsterdam. As their user base grows, Jan is having trouble with making sure his users are paid out consistently at a set interval. This has proven quite troublesome as more and more users join their marketplace. Jan is looking for some kind of automation. This is where sweeps come into play, an Adyen feature that allows him full control of his payout functionality. Sweeps pull in or push out funds from a balance account based on a predefined schedule, amount, currency, and a source or a destination.

Before we delve into the specifics, let’s clarify two key terms:

Account holder: This refers to the user entity within the balance platform. Depending on your account structure, the account holder can either be your company, or your customers.
Balance account: This is the account where funds are held for an account holder. All financial activity happens through balance accounts. Each account holder can have one or more balance accounts for accounting flexibility, but in most use cases, a single balance account is sufficient.

An account holder can be one of the following legal entities: Individual, Business, Nonprofit, Partnership, or Public company. To create an account holder, send a request to the /createAccountHolder endpoint. Refer to this documentation page to understand the different request parameters for each legal entity.

Account holders rely on the platforms for the benefit of their business but also for features like reliability and ease of access to their funds. The skeleton of reliability, trust and ease are equal parts of a massive pillar in this business model. The core of this trust relies on the payout functionality being spot on and easy for both the account holders and the platforms to configure and customize based on their needs.

What types of sweeps exist?

A sweep automatically pushes out or pulls in funds from a balance account based on a predefined schedule, amount, and source or destination. There are two types of sweeps that exist as part of the Adyen Balance Platform.

The push sweep
The pull sweep

The push sweep

The push sweep is the type of sweep used for configuring payouts. Platforms use this type of sweep to send a payout to the account holders based on a configurable schedule and other additional parameters such as the currency.

The push sweep is configured for the balance account of the account holder. This means that an account holder with multiple balance accounts can define sweeps with different configurations, based on the preferences of the business case.

The pull sweep

The pull sweep is the type of sweep used for the auto-funding functionality on the balance platform for account holders. Platforms can use this type of sweep to pull funds into a designated balance account when a certain threshold is reached.

Auto-funding use cases are those as old as time, where an account holder needs funds to process refunds but is below a threshold to process them successfully. At this point, the autofunding functionality configured via a pull sweep comes to the rescue by pulling in funds for operational ease.

How to configure sweeps

You can configure sweeps for balance accounts through two primary methods:

Customer Area
API functionality

Customer Area

You can directly configure sweeps for balance accounts via the Customer Area by performing the following steps:

Log into the Customer Area using your credentials.
Navigate to the account holder.
Navigate to the balance account you want to configure the sweep for.
On the balance account page, use the button as shown below to add a sweep configuration for the balance account. Choose the type of sweep you would like to configure. For the purpose of this example, we will be proceeding with the push sweeps for payouts.

Once the type of sweep has been selected, you will proceed to a page with an extensive range of customization options that allow you to tailor the structure of your sweep according to your preferences.

Finally confirm the configuration by clicking next and viewing the summary of the sweep you are ready to create.

API functionality

For developers, it is possible to use the Adyen Platform Configuration APIs for automating the sweep configurations for account holders.

You can create a sweep by specifying its type and send a POST request to the /balanceAccounts/{balanceAccountId}/sweeps endpoint. You can configure the request parameters in the body of the API call as shown below. For a more detailed overview on what each of these parameters do, read our API documentation here.

Create a push sweep using a POST request:

{
    "counterparty": {
      "balanceAccountId": "BA3233T22337JX5JVZFTEPC91B" // The destination of the funds
    },
    "currency": "EUR", // The currency of the sweep
    "schedule": {
      "cronExpression": "30 9 * * 3", // The cron expression for the schedule when the sweep is validated
      "type": "cron" // The schedule when the sweep is evaluated
    },
    "type": "push", // The direction of the sweep
    "description": "Internal funds transfer every Wednesday at 0930"
}

A successful request returns the newly created push sweep.

{
  "id": "SWPC4233T22337JX5JVZGSP39S4M7K",
  "schedule": {
    "type": "cron",
    "cronExpression": "30 9 * * 3"
  },
  "status": "active",
  "targetAmount": {
    "currency": "EUR",
    "value": 0
  },
  "triggerAmount": {
    "currency": "EUR",
    "value": 0
  },
  "type": "push",
  "counterparty": {
    "balanceAccountId": "BA3233T22337JX5JVZFTEPC91B"
  },
  "currency": "EUR",
  "description": "Internal funds transfer every Wednesday at 0930"
}

Adyen will also asynchronously send the "balancePlatform.balanceAccountSweep.created" webhook with the sweep response. You can find an example of the webhook payload below.

{
  "data": {
    "balancePlatform": "YOUR_BALANCE_PLATFORM",
    "accountId": "BA3233T22337JX5JVZGSPD9B9",
    "sweep": {
      "id": "SWPC4233T22337JX5JVZGSP39S4M7K",
      "schedule": {
        "type": "weekly"
      },
      "status": "active",
      "targetAmount": {
        "currency": "EUR",
        "value": 0
      },
      "triggerAmount": {
        "currency": "EUR",
        "value": 0
      },
      "type": "push",
      "counterparty": {
        "balanceAccountId": "BA3233T22337JX5JVZFTEPC91B"
      },
      "currency": "EUR"
    }
  },
  "environment": "test",
  "type": "balancePlatform.balanceAccountSweep.created"
}

Summary

In summary, we've covered sweeps using a real-life example and discussed the two types of sweeps: push and pull. We've shown how to set these up through the Adyen Customer Area or using API calls. Going back to our introduction, Jan now has a better understanding of how this works and he can now feel more confident about the functionality as it allows him just the right amount of control over the payouts for his customers. This means that his users can continue selling and buying cars on his platform without having to worry whether they get their money on time.

Are you looking for more developer-related content? Have a look at developers.adyen.com today or let us know on Twitter what you’d like to see next!

Using Adyen to Implement Payment Pre-authorizations and Authorization Adjustments

Kwok He Chu — Wed, 18 Oct 2023 16:43:20 +0000

This technical blog post explains how developers can implement a hotel booking payment process using Adyen's API. It covers pre-authorizations, amount adjustments, extending authorization expiry dates, capturing payments, refunding payments and webhook payloads.

At Adyen, we understand that modern businesses across different industries require various payment solutions for different use cases. In a basic payment flow, the amount from your payment request is authorized and then captured. But sometimes you may want to change the amount or extend the length of the authorization. This is known as a pre-authorization, followed by an authorization adjustment.

Introduction

The use of authorization adjustment in various industries may differ. One could increase the amount, decrease the amount after a successful pre-authorization or extend the expiry date of the authorization.

In the hospitality sector, for example, hotels use pre-authorizations to facilitate payment processes before a guest checks into their hotel. During their stay, if the guest incurs additional expenses at the hotel, these expenses can be added to the pre-authorized amount by adjusting the authorization. Once the guest checks out, the hotel captures the final amount or, optionally, cancels the payment if the guest prefers to settle their bill with a different payment method.

In other cases such as taxi rides, car rentals, or parking, you can use pre-authorizations to handle situations where the final amount for the service is not known at the time of payment.

Another common use-case is in the United States. As tax regulation can differ widely between states, it is common that the final amount of an order for clothing and apparel deliveries has to be adjusted due to tax regulation changes in applicable tax due to last minute changes of origin or destination of the package.

Overview

Let’s start by taking a look at a high-level technical overview where a guest reserves a hotel room for $249.99 and chooses to accumulate extra costs during their stay. Here’s an overview of the three main request:

Pre-authorization request: The merchant initiates a pre-authorization request of $249.99.
Authorization adjustment request: Once the pre-authorization is successfully authorized, the merchant sends an authorization adjustment request of $500.
- Extension request: Once a pre-authorization request is successfully authorized, the merchant can optionally extend the authorization to increase the expiry window of this authorization.
Capture request: Once the authorization adjustment is successful. The merchant confirms the final payment by sending a capture request of $500. This will finalize the payment.
- Reversal request: Optionally, a merchant can cancel or refund the authorization with a reversal request.

1. Pre-authorization

First, we create a pre-authorization request to the /payments endpoint. We specify a merchant reference to keep track of the payment throughout the whole payment lifecycle.

Pre-authorization request:

{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "reference": "7a5d8be7-cceb-4442-b17f-3a10a8fa396d", // Your unique reference
  "channel": "Web",
  "amount": {
    "currency": "USD",
    "value": 24999 // 249.99 USD in minor units
  },
  "returnUrl": "https://your-company.example.com/api/handleRedirect?orderRef=7a5d8be7-cceb-4442-b17f-3a10a8fa396d", // We redirect to our domain
  "countryCode": "NL",
  "paymentMethod": { 
     "type": "scheme",
      "number":"4111111111111111",
      "cvc":"737",
      "expiryMonth":"03",
      "expiryYear":"2023",
      "holderName":"John Smith"
  },
  "additionalData": {
    "allow3DS2": "true",
    "authorisationType": "PreAuth"
  }
}

A successful response contains the “Authorised” result code.

Pre-authorization response:

{
   "additionalData" : {
      // …
   },
   "pspReference" : "TJ5MXF5SK3RZNN82",
   "resultCode" : "Authorised",
   "amount" : {
      "currency" : "USD",
      "value" : 24999 // 249.99 USD in minor units
   },
   "merchantReference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
   "paymentMethod" : {
      "brand" : "visa",
      "type" : "scheme"
   }
}

Adyen will send a webhook asynchronously, check the notification success-flag to see whether the authorization has succeeded.

"AUTHORISATION" webhook:

{
   "live" : "false",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
      // …
               "hmacSignature" : ""**********************",",
             // …
            },
            "amount" : {
               "currency" : "USD",
               "value" : 24999 // 249.99 USD in minor units
            },
            "eventCode" : "AUTHORISATION",
            "eventDate" : "2023-07-06T15:07:38+02:00",
            "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
            "merchantReference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
            "operations" : [
               "CANCEL",
               "CAPTURE",
               "REFUND"
            ],
            "paymentMethod" : "visa",
            "pspReference" : "TJ5MXF5SK3RZNN82",
            "reason" : "052031:1111:03\/2030",
            "success" : "true"
         }
      }
   ]
}

The webhook contains a PspReference that can be used in the subsequent authorization adjustment call.

2. Authorization Adjustment

To adjust the amount asynchronously, we create a request object to the /payments/TJ5MXF5SK3RZNN82/amountUpdate endpoint. The

Authorization adjustment request:

{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "Currency": "USD",
    "Value": 50000 // 500 USD in minor units
  },
  "Reason": "DelayedCharge",
  "reference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d"
}

Authorization adjustment response:

{
    "industryUsage": "delayedCharge",
    "status": "received",
    "amount": {
        "currency": "USD",
        "value": 50000
    },
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "paymentPspReference": "TJ5MXF5SK3RZNN82",
    "pspReference": "WBG6F4K25HXXGN82",
    "reference": "7a5d8be7-cceb-4442-b17f-3a10a8fa396d"
}

The call is received by Adyen when the response status matches the expected "received" status.

Later on, Adyen sends a webhook with an “AUTHORISATION_ADJUSTMENT” event code that contains the result of the authorization adjustment. Check the success-flag to see whether the adjustment has been successful and save this accordingly in your backend.

"AUTHORISATION_ADJUSTMENT" webhook:

{
   "live" : "false",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
               "hmacSignature" : "********************",
               "bookingDate" : "********************" // This is a DateTime
            },
            "amount" : {
               "currency" : "USD",
               "value" : 50000
            },
            "eventCode" : "AUTHORISATION_ADJUSTMENT",
            "eventDate" : "2023-07-06T16:01:28+02:00",
            "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
            "merchantReference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
            "originalReference" : "TJ5MXF5SK3RZNN82",
            "paymentMethod" : "visa",
            "pspReference" : "WBG6F4K25HXXGN82",
            "reason" : "",
            "success" : "true"
         }
      }
   ]
}

Validity and authorization expiry dates

Card schemes set specific rules around which businesses (f.e. travel, restaurants, public transportation) are able to adjust an authorization. Your merchant category code (MCC) determines the eligibility, together with the card scheme. You can find an extensive table on availability here.

Adyen expires authorization requests automatically after 28 days from the day the payment is authorized. Note: Please refer to the documentation to see a table as these vary per card scheme. The default expiry period can be adjusted and ensures that Adyen does not automatically expire the authorization after the default 28 days. Our support team can configure this for your merchant account.

If you try to capture a transaction after the allowed time, it's more likely to fail. However, you can often capture a payment successfully after an authorization has expired. Depending on the card scheme, there can be a fee for late captures, and an increase in interchange and/or scheme fees charged for the transaction. There's also a higher risk of chargebacks from card holders.

To manually extend the expiry date of an authorization, make a request to the same endpoint but leave the amount unchanged.

Authorization adjustment extend request:

{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "Currency": "USD",
    "Value": 24999 // 249.99 USD in minor units
  },
  "Reason": "DelayedCharge",
  "reference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d"
}

Authorization adjustment extend response:

{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "amount": {
    "Currency": "USD",
    "Value": 24999 // 249.99 USD in minor units
  },
  "Reason": "DelayedCharge",
  "reference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d"
}

“AUTHORIZATION_ADJUSTMENT” extend webhook:

{
   "live" : "false",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
               "hmacSignature" : "********************",
               "bookingDate" : "********************" // This is a DateTime
            },
            "amount" : {
               "currency" : "USD",
               "value" : 24999
            },
            "eventCode" : "AUTHORISATION_ADJUSTMENT",
            "eventDate" : "2023-07-06T16:21:28+02:00",
            "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
            "merchantReference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
            "originalReference" : "TJ5MXF5SK3RZNN82",
            "paymentMethod" : "visa",
            "pspReference" : "WBG6F4K25HXXGN82",
            "reason" : "",
            "success" : "true"
         }
      }
   ]
}

3. Capture

To finalize the payment, make sure you’ve received the webhook for each authorization adjustment that you’ve made. Make a request to the endpoint /payments/TJ5MXF5SK3RZNN82/captures with the final amount of $500 that you wish to capture. Notice that we're using the PspReference of the initial pre-authorization.

Capture request:

{
  "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
       "amount":{
          "Currency": "USD",
          "Value": 50000 // 500 USD in minor units
       },
   "reference":"7a5d8be7-cceb-4442-b17f-3a10a8fa396d"
}

Capture response:

{
   "merchantAccount" : "YOUR_MERCHANT_ACCOUNT",
   "paymentPspReference" : "TJ5MXF5SK3RZNN82",
   "pspReference" : "FVNHBFGDFVTFWR82",
   "reference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
   "status" : "received",
   "amount" : {
      "currency" : "USD",
      "value" : 50000 // 500 USD in minor units
   }
}

Adyen sends a webhook with the event code “CAPTURE” when successful or unsuccessful. In some rare cases a "CAPTURE_FAILED" event code (with a success-flag) can occur as well. This can happen because it was either rejected by a card scheme, technical issue, or when capture expires. For a full list of failed capture reasons, refer to this documentation page on what to do next.

Successful “CAPTURE” webhook:

{
   "live" : "false",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
               "hmacSignature" : ""********************"",
               "bookingDate" : "********************"
            },
            "amount" : {
               "currency" : "USD",
               "value" : 50000 // 500 USD in minor units
            },
            "eventCode" : "CAPTURE",
            "eventDate" : "2023-07-06T16:50:16+02:00",
            "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
            "merchantReference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
            "originalReference" : "TJ5MXF5SK3RZNN82",
            "paymentMethod" : "visa",
            "pspReference" : "FVNHBFGDFVTFWR82",
            "reason" : "",
            "success" : "true"
         }
      }
   ]
}

If you use an invalid PspReference (f.e. when you use the PspReference from an authorization adjustment response), you’ll receive a webhook containing a "transaction not found" message. Likewise, if you attempt to recapture a payment that has already been captured, you will receive an unsuccessful webhook notification with the reason field indicating "Insufficient balance on payment."

Unsuccessful “CAPTURE” webhook:

{
   "live" : "false",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
               "hmacSignature" : ""********************"",
               "bookingDate" : "********************"
            },
            "amount" : {
               "currency" : "USD",
               "value" : 50000
            },
            "eventCode" : "CAPTURE",
            "eventDate" : "2023-07-06T16:45:55+02:00",
            "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
            "merchantReference" : "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
            "originalReference" : "WBG6F4K25HXXGN82",
            "pspReference" : "N99H9LX8NV5X8N82",
            "reason" : "Transaction not found",
            "success" : "false"
         }
      }
   ]
}

Reversals
To cancel or refund a payment, send a request to the /payments/TJ5MXF5SK3RZNN82/reversals endpoint. Notice that we're still using the PspReference TJ5MXF5SK3RZNN82 from the initial pre-authorization. This request is useful when you want to return the funds to your guest, but are not certain whether the payment has been captured or not.

This will either:

Cancel the payment – in case it has not yet been captured.
Refund the payment – in case it has already been captured.

Reversal request:

{
    "reference": "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}

Reversal response:

{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "paymentPspReference": "TJ5MXF5SK3RZNN82", // The original pre-authorization pspReference
    "pspReference" : "GF445R8G6L2GWR82",
    "reference": "7a5d8be7-cceb-4442-b17f-3a10a8fa396d",
    "status" : "received"
}

“CANCEL_OR_REFUND” webhook

{
   "live":"false",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "modification.action": "refund"
            },
            "amount":{
               "currency": "USD",
               "value": 50000
            },
            "eventCode":"CANCEL_OR_REFUND",
            "eventDate":"2023-07-06T17:25:23+02:00",
            "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
            "originalReference":"TJ5MXF5SK3RZNN82", // The original pre-authorization pspreference
            "paymentMethod":"mc",
            "pspReference":"GF795R5G6L2GWR82",
            "reason":"",
            "success":"true"
         }
      }
   ]
}

Now that we’ve seen the flow, here’s a diagram containing the success scenarios.

You send a pre-authorization request to Adyen.
After some time, Adyen sends an AUTHORISATION webhook.
A successful AUTHORISATION webhook can be adjusted.
- (3A) A successful AUTHORISATION webhook can be captured.
- (3B) successful AUTHORISATION webhook can be canceled or. refunded
A successful AUTHORISATION_ADJUSTMENT webhook can be captured.
- (4A) A successful AUTHORISATION_ADJUSTMENT webhook can be canceled or refunded.
A successful CAPTURE webhook can be canceled or refunded.
After receiving a successful CANCEL_OR_REFUND webhook, the refund can still be rejected by the card scheme. There are two webhooks that may be sent afterwards.
- REFUND_FAILED webhook.
- REFUNDED_REVERSED webhook.

"REFUND_FAILED" webhook
When Adyen sends a successful REFUND webhook, it means that our validations were successful and we sent the refund request to the card scheme. However, the card scheme can still reject the refund. This can happen even a few days after you submitted the refund request. To handle these failure reasons, refer to our documentation on what to do next.

To test failed refunds, you can make a pre-authorization request and enter the holder name “refund failed”, to test this scenario.

"REFUNDED_REVERSED" webhook
For some payment methods, for example bank transfers, iDEAL, or Bancontact, the status of the payment can change from “REFUND” to “REFUNDED_REVERSED”. This means that the funds have been returned to Adyen, and are back in your account. This can happen, for example, if the bank account is no longer valid.

Below you can find a full chart of the webhooks with the different event codes. Red indicates that the “success”-flag is set to false, while green indicates that the webhook was successful.

You can find a fully working integration-example on our Github page.

Summary

We’ve seen how you can use Adyen pre-authorizations and authorization adjustments to implement a hotel booking use case. We’ve gone over the API responses and webhooks that a developer can encounter. The following steps were described in-depth:

Perform the pre-authorization request
Increase or decrease the amount using authorization adjustments; optionally extend the expiry date of the authorization
Capture the final amount
Perform payment reversals (cancel or refund)

We’re always looking for ways to improve our existing integration examples or build new integrations for our developers.

Have a look at developers.adyen.com today or let us know on Twitter what you’d like to see next!

Building a feature platform guided by your ethos

Julien Lengrand-Lambert — Wed, 04 Oct 2023 08:06:16 +0000

In this blog, we discuss our decision process to build a data platform that is powerful but yet stays guided by our ethos.

My wife and I are quite different in our shopping habits. She likes analysing the market trends and she’s good at deciding what she likes. She’s even better at deciding whether to buy or not — disclaimer: usually she does buy it, and then our entrance at home looks like a package pick-up point (not true, but also not entirely not-true).

I, however, have a different poison. When I am looking for something, say a new set of headphones, I analyse and analyse again, and at some point I conclude that a certain product is probably the best fit for what I am looking for. Then, I check, yet again, the distance for the second choice and after that I might end up going back to the fundamental question of whether I actually needed it in the first place.

I am quite frugal, so if I am not very enthusiastic about the top choice I will probably end up discarding it (and bloating those non-conversion metrics for the A/B test behind the ecommerce site that leaves the team scratching their head about what is wrong with their website).

In my defence I will say that if I am sure I need something and there is a clear market winner, I buy immediately and I do not think about it anymore.

The point is, choosing what to buy and when to buy it, is quite transcendental. Choosing your tech stack is a somehow similar problem. You need to understand and reflect very well on a number of things:

Whether you actually need it, or is a fun exciting but limited-value exercise (hello ChatGPT demos 🙊)
How do you sweep and track the market and assess which tool or framework to adopt?
Should you build or buy?
How fast do you need it and whether you are sacrificing something instead?

Without thorough consideration of the above, a leadership team (often proud of their choice and/or invested in another way) may spiral the team downwards in terms of productivity and motivation. That’s why it is important to give it the right amount of love, and eventually make a well-informed choice together with the technical experts.

It is remarkably difficult if you end up in a situation where there’s a clear need for something better than what you have now but there is no industry standard or a clear choice. That’s where my shopper-persona would collapse, and a Feature Store, or should I say Platform (will come to that later), has been a primary example of this sort of conundrum. At Adyen we have gone through this exercise a number of times and we have learned, sometimes the hard way, how to go about these choices. It really boils down to two things that we embrace in our ethos: iterating and control.

Our first attempt to build a Feature Store

Let me use an example of a use case for a feature store at Adyen. Every payment that goes through Adyen — and we do a lot of those (860 billions USD in 2022) — undertakes a journey where a number of decisions are made through an inference service fueled by a machine learning model that we have trained and deployed. We have a few instances of those services with different purposes: our risk system (is the transaction fraud or legit), our authentication service (should we authenticate the user, and if so in which way), our routing algorithm, our transaction optimiser, our retry logic and others.

We are talking about a service that can take several thousands of requests per second per model and respond in less than 100 ms. The final goal of all these models is to land as many good transactions as possible in the most efficient way, without ending up in a chargeback or a retry or higher costs.

Now, these models need features, of course. They need features both at training time and at scoring time.

Let’s zoom in on the risk system. The service was initially built through rules across three different data sources:

Block/allow look-up-tables, powered by PostgreSQL.
Velocity database, powered by PostgreSQL, and able to provide information such as how many times has this card been used in this last minute.
Our “shopper” database, also powered by PostgreSQL.

The “shopper” database deserves its own paragraph. We have used, and maybe even abused, PostgreSQL in a very beautiful way: to identify shoppers in real time. This system in the end provides an elegant and simple graph algorithm by identifying communities of attributes (cards, emails, …) that relate to the same person. It does that very efficiently and very fastly, but it has its own complications around flexibility and scalability. My colleague Burak wrote a great article about it.

When introducing a new approach based on a supervised classifier, we thought: hey, let’s include features about the merchant, that’ll boost AUCPR. Small note, a merchant in the fintech jargon is a seller or a company, take for example, Uber or Spotify. In this sense then, we’d include, as a feature, datapoints like the size of the merchant, the country of the merchant, for how long have we been processing for this merchant, the authorisation rate of that merchant across different sliding windows and so on.

However, many of these example features are slow-moving, medium cardinality, high data volume, features. And PostgreSQL wasn’t gonna cut it in terms of crunching all that volume. So we added a new database called “Feature Store” (read that as Dr. Evil with his famous quote hands).

We took advantage of the fact that we were sending all our transaction events to our Big Data Platform via Kafka. We collect all this info in the form of Hive tables and then we use Spark to crunch all this information, all beautifully orchestrated through Airflow. We had all this information and tooling available in our Big Data Platform because that’s where we train our models. We just need to use an abstraction layer to define the features (we chose Feast) and then deploy on another posgresql instance in the real-time flow (we love postgresql, in case you haven’t figured this out yet). The ML artifacts are deployed to our real-time platform through our wrapper around MLflow, called Alfred, that allows us to stage their rollout into ghost, test, canary live settings and default live modes.

The final picture to our first crack at a “Feature Store” looks like this.

And happy we were ever after, thinking that we had a “Feature Store”. And by “ever after” I mean a couple of months.

The build-vs-buy tradeoff

Hidden in all this there’s something that might have passed unnoticed, the redux of a very important lesson that we have learned through the years: our build-vs-buy trade-off.

There are great vendors that promise and deliver a seamless turn-key experience: it’s fast and it just “works”. It’s a very amenable choice, and I can only show my honest respect for these startups: they are like rain in the middle of a drought for a lot of companies that want to instantly get in the gig of Feature Stores, MLOps, Experimentation, Data Governance and any other sweet problem to solve. And they do a good job at it.

At Adyen, we like to stay in control and understand what happens under the hood. We also have a very solid principle: we won’t use a vendor for anything touching our core business. In this case, processing a payment is indeed core business and we don’t want to introduce a dependency on a third-party. That has two important implications that are worth calling out:

First, we do use vendors, but we are critical about which part of the system they impact. On the one hand we buy our laptops from a vendor — it wouldn’t be optimal if we had a team building laptops. On the other hand, because we are set in building for the long term, we believe in controlling all our supply-chain (take SpaceX, procuring their own screws even).

Second. If we don’t use vendors, do we then build in-house? We have made that choice in the past, and now in perspective, it was a mistake. Picture a top-performing engineer, machete in their teeth, mumbling a classical “hold my beer” and then proceeding to build from scratch something that already exists because “it will only take me a week to do it better”.

We have been there and after the first month I can guarantee the fun is over. Looking ahead at the feature parity roadmap sinks you in despair, the operational debt and preventable bugs itch you more than usual, and you end up going to bed every night thinking “why did we do this”.

So what’s the answer?

Well, open source.

We use open source as much as possible to build our infra and rails, and then we build on top of it our core business. We also contribute back by merging PRs and adding new features that we found useful. At the end of the day, the internet runs on open source.

Iterating on the Feature Store

I already gave away one bit of our ethos: strong control of our dependencies, fueled by long-term thinking. A second big trait of our way of thinking is the iteration culture.

At some point when building software, and even hardware systems, someone figured out that working in waterfall contracts doesn’t really help and that instead working in an agile way gets you further and faster, and it is also more fun. The point of agile is not to adopt scrum. The point of agile is to embrace that the MVP is minimum (and therefore rusty and barely presentable) and also viable (it works, it’s not a WIP commit), and from there onwards, you have to iterate and quickly.

We took a cold look at what we had built that we proudly called “feature store”, tried to remove any emotional attachments to it, and ended up concluding that it wasn’t actually great. We also conclude that we might want to do some soul-searching and write a requirement list about what we want the whole thing to do.

We ended up with a letter to Santa with everything we wanted. At least from there we could make a conscious choice about what we will not get given the cost and possibilities.

Feature Parity: the features and values on the training and scoring flows must be identical.
Retrieval latency: we need the inference service to work under 100 ms, so there’s that.
Recency: the features should not be old, we should be able to refresh them very fast.
Cardinality: we want to be able to store billions of features.
Distributed: we need instances of the feature store around the world, because we process globally.
Storage / Scalability: our transaction volume grows quite a lot every year, and we build for 20x.
Availability / Uptime: we need the system to be there 99.99999% of the time.
Self-service: ideally we want data scientists to go about themselves when prototyping and deploying new features
Complex calculation: some of these features can be complex to compute, that should be alright.
Feature diversity: it’d be great if we didn’t have to maintain three different databases and we just had one endpoint with all sorts of data inside.

After seeing that list we thought “wow, it’s a long list” but we also figured that there was an underlying difference between a pure storage place and a place where things are computed. And that’s also where we read Chip Huygen’s fantastic article on Feature Platforms, and it was one of those click/a-ha moments, when you confidently say out loud “we were building a feature platform, not a feature store” and you can hear the non-existent triumphant music behind you.

The main difference lies in facilitating the computing of features, apart from the storing and serving which is indeed captured under the definition of the feature store.

The new blueprint

Based on this we also saw the need to have a system that spans across two different platforms, our real-time platform (where payments, KYC, payouts, refunds and financial interactions with the world happen) and our big data platform (where we crunch the data). That’s not a surprise given that you have a need in two very different flows: your inference flow in real-time and your training flow off-line.

We needed an abstraction layer that would glue both systems and we chose to keep on using Feast, the open source package to allow data scientists and engineers to define features uniquely and ensure consistency across the two environments. We also evaluated LinkedIn’s Feather, but we deemed it too opinionated and opted for the openness of Feast.

The general idea behind the synching happening on the two environments is that some features will be computed on the real time flow and stored on hot storage and sync back to the cold storage (big data platform) while the slow-moving features will be computed on the big data platform, stored there (cold storage) and synched to the hot storage for inference.

While the batch computation engine and storage were already there, Spark and Hive/Spark/Delta, we still had a few choices to make regarding the on-line flow. For stream computing we are inclined to use Apache Flink — but we can define it later. For the storage layer we hit a dilemma across a few contenders: Redis, Cassandra, Cockroach and sweet old posgresql.

Here is where I will circle back to where I started: you need to make good decisions and that probably means that you need to involve technical experts. Even there, you also want to be able to tap into the wider organisation to make sure that you are not too biassed or forgetting anything. That’s why we have a TechRadar procedure where engineers can share ideas for technology contenders, spar, benchmark and eventually decide on which to adopt in a “makes sense” fashion.

We decided for Cassandra. Redis’ in-memory storage makes it quite expensive at the cardinality we are looking for, Cockroach is really keen on read-write consistency at the expense of speed and posgresql, well, didn’t cut it for our needs.

We still are evaluating choices for on-line computing engines (as said, Flink looks good) and feature monitoring, where it might be that we just use the monitoring stack available, largely consisting of Prometheus, Elastic and Grafana.

That’s an honest look at where we are today. We are making an informed choice and not shooting from the hip. We have determined what we need, we have also determined what is important to us and what we are willing to pay for it. We have analysed the market and open-source offering and are back to our beloved execution mode.

Even if there’s no clear and obvious choice, my shopper persona is still happily going through this procurement journey and enjoying the benefits of learning, discovering the possibilities and deciding. Because if we don’t get it right at first, we will build, fail, learn and iterate.

Guide: Upgrade and customization for Salesforce Commerce Cloud cartridge

Ayodeji Ogundare — Fri, 01 Sep 2023 13:52:28 +0000

In this guide, discover the importance and process of upgrading your Salesforce Commerce Cloud (SFCC) cartridge to the latest version to create a hassle-free integration and seamless checkout experience benefitting both you and your customers. We'll highlight best practices for customizations and walk you through the process of adding custom code to a new cartridge, ensuring a smooth transition to the latest releases.

As an online business owner, ensuring a smooth and seamless checkout experience for your shoppers is vital to success. To achieve this, customizations are often necessary to tailor your checkout process to meet specific needs. To take advantage of new features, bug fixes, and security patches, you’ll need to stay up-to-date with the latest cartridge version.

This guide is specifically tailored to users of the Salesforce Commerce Cloud Storefront Reference Architecture (SFRA). If your e-commerce platform does not utilize SFRA, some of the outlined steps and procedures may not be directly applicable.

The benefits of upgrading your cartridge

Upgrading your cartridge to the latest version offers several benefits that can significantly enhance your checkout experience. Here's why you should consider upgrading:

Access to new features: Each cartridge release comes with exciting new features that can improve the overall functionality and usability of your checkout process. This ensures that you offer your customers the best shopping experience.
Bug fixes and security patches: As with any software, cartridges might have bugs or security vulnerabilities. Regular updates and upgrades address these issues, not only ensuring that your checkout process remains secure, but also improving the authorization rate.
Compatibility with integrations: Third-party integrations and platforms continually evolve, and cartridge updates often ensure compatibility with the latest versions of these integrations. Upgrading your cartridge reduces the risk of conflicts and ensures a seamless connection with your preferred tools.
Continued Cartridge support: We provide support and assistance for the latest versions, making it easier to troubleshoot issues and seek guidance whenever needed.

Customization guide for smoother upgrade (SFRA)

Merchants use customizations to communicate their brand value to shoppers. Customizations are a great way to offer a unique shopper experience. Unfortunately, if customizations are implemented inside of the cartridge, they obscure future cartridge upgrades and introduce technology bottlenecks. We've created a 4-minute video to help you decouple your customizations and upgrade a customized cartridge to the latest version. You can skip the video if you prefer a step-by-step text guide.

Step 1: Add custom code to a new cartridge

To make future upgrades and troubleshooting easier, add your custom code to the int_custom_cartridge folder in your src/cartridges directory. If this folder is not available in your version, create a new folder and name it; int_custom_cartridge and add your custom code. This setup will allow you to temporarily remove custom code during upgrades or troubleshooting.

# Add your custom code to the int_custom_cartridge folder
# Modify the code as needed to customize the checkout experience. For example, in JavaScript:

# File: int_custom_cartridge/scripts/customization.js

function customizeCheckout() {
  // Your custom code here
  console.log("Custom checkout code executed.");
}

Step 2: Include custom cartridge in package.json file

Update the name property in the package.json file to int_custom_cartridge or the name you chose for your custom cartridge.

# Update package.json to support the custom cartridge
# File: int_custom_cartridge/package.json
{
  "name": "int_custom_cartridge",
  "version": "1.0.0",
  "description": "Custom cartridge for checkout customization",
  // Other package.json properties
}

# Update root package.json to contain the new cartridge in the build step
# Make sure you are in the root directory of your project and run

npm install
npm run build

Step 3: Add the new cartridge to your cartridge path

In the Business Manager, navigate to Administration > Sites > Manage Sites > [yourSite] > Settings. In the Cartridges field, add the new cartridge before the Adyen cartridges. Click “Apply” to save your changes.

Step 4: Modify or add end-to-end tests (optional)

To ensure your custom code works correctly, modify or add end-to-end tests as needed. Running these tests will validate the functionality of your customizations.

Upgrade guide for different integrations

Depending on your integration type (Default or Customized), the upgrade process varies:

Default integration

Check which SFRA version is required for the upgrade and migrate if necessary, aiming to use the highest available SFRA version
Download the desired Adyen cartridge version from GitHub
Transpile, compile, and upload the compatible, auto-generated code using npm run build
Re-upload the metadata

# Download the desired Adyen cartridge version from GitHub
# Replace '23.1.0' with the version you want to upgrade to
git clone https://github.com/adyen/adyen-salesforce-commerce-cloud.git --branch 23.1.0

# Re-upload the metadata
# Make sure you are in the root directory of your project
cd adyen-salesforce-commerce-cloud

# Transpile, compile, and upload the compatible, auto-generated code
npm run build

# Zip the site_import folder
zip -r adyen_integration.zip package/metadata/site_import/sites

# In Business Manager, go to Administration > Site Development > Site Import & Export
# Import the zipped file (site_import.zip)

Customized integration

For a quick demo of how to upgrade the SFCC cartridge with customization, watch this 2 mins video.

Steps:

Extract any custom code from the cartridge and place it in the custom cartridge (int_custom_cartridge) folder. Create a new folder if not available in your version.
Check SFRA version requirements and migrate if needed
Download the desired Adyen cartridge version from GitHub
Update the package.json as explained above and run npm run build
Re-upload the metadata
Update the cartridge path in the Business Manager to include your customizations

Conclusion

In today's competitive e-commerce landscape, the checkout experience can make or break a customer's decision to complete a purchase. As an online business owner, customizing your checkout process is essential to cater to your unique requirements and create a branded experience that resonates with your audience. However, these customizations must not come at the cost of missing out on crucial updates and improvements.

By following this guide to upgrading your cartridge to the latest version, you can strike the perfect balance between customization and innovation. Embrace the latest features, bug fixes, and security patches to ensure a seamless and secure checkout journey for your shoppers.

Upgrading your cartridge to the latest version is more than just a technical necessity - it's an investment in your business's success. Stay ahead of the competition by accessing new capabilities that improve the functionality of your checkout process and enhance customer satisfaction. Take your e-commerce venture one step closer to excellence.

So, are you ready to unlock the full potential of your checkout process? Your dedication to providing the best checkout experience will not only increase conversion rates but also foster customer loyalty.

Upgrade today and let your checkout experience set the gold standard for online shopping!