Adyen locale vs countryCode: what is the difference?

What each one actually controls

countryCode goes on the session and is a commercial setting. Adyen uses it, together with the currency and amount, to decide which payment methods your merchant account can offer this shopper. Change it from NL to US and iDEAL disappears while ACH Direct Debit appears. It also drives formatting, so address fields and amount display follow local convention.

locale is a presentation setting. It selects the translation used for labels, validation messages and button text. It has no influence at all on which methods you get.

Both being independent is the point. A Dutch-speaking shopper buying from your German store is locale: 'nl-NL' with countryCode: 'DE', and that combination is entirely legitimate.

This applies the same way whether you are on Drop-in or Components, since both take the settings from the session and the component config rather than from anything the page does on its own.

Changing locale needs a new component

This is the part that costs an afternoon. If you change locale after the component exists, remounting the instance you already have will not change the language. The translation is resolved when the component is created, so you have to create it again.

It matters on any checkout with a language switcher, because the obvious implementation, updating the config and remounting, appears to do nothing and gives you no error to search for.

Currency is a third thing

Worth saying because it gets folded into the same confusion. Currency lives on the session amount, not on either of these settings. A common working combination is countryCode: 'NL' with EUR, but nothing stops you from pairing a country with a currency that has no local methods, in which case the shopper sees cards and little else.

Try it yourself

Both Adyen playgrounds expose locale and countryCode as separate controls, so you can change one at a time and watch which one moves the method list and which one moves the words.