adyen-notes.md

Adyen Notes

General API docs notes

• https://docs.adyen.com/api-explorer/#/CheckoutUtility/v1/originKeys

• All REST endpoints are POST endpoints.

• All POST requests should have the following headers:

  • "Content-Type: application/json"
  • "X-API-KEY: $YOUR_KEY"
  • Example: curl -X POST -H "Content-Type: application/json" -H "X-API-KEY: $YOUR_KEY" -d '{"originDomains:[{"https://www.zeddee.com"}]}' https://checkout-test.adyen.com/v1/originKeys

• Integration checklist: https://docs.adyen.com/development-resources/integration-checklist

  • Contains step-by-step
  • So far looks like the best entrypoint doc, but buried under Development Resources as the last topic/page.

Adyen POST idempotency

• Adyen's POST endpoints "support" idempotency.
• Wording is vague on https://docs.adyen.com/development-resources/api-idempotency, but I gather that:
  • Adyen's POST endpoints do not perform idempotent actions out-of-the-box.
  • To make POST requests idempotent, you must send the POST request with a "Idempotency-Key:<key>" header, where <key> is a user-defined string of up to 64 chars. Each (The docs recommend using a UUID of sorts).
• If the resource for the POST request already exists, the Adyen servers will return a response for the first attempt at the POST request.
• An idempotent POST request returns a response with the same "Idempotency-Key" header.
• The value of <key> is stored at a company account level.
• docs say that <key> must be unique to the company account, but what this means is not clear. Does "unique to company account" mean that:
  • Each request must use a unique key? But the scope of that key is only within the company account, and only needs to be unique within the company account?
  • Each API-KEY (and therefore, user account) must use a unique key, and that uniqueness is scoped only within the company account?
  • Each key must be unique throughout Adyen? Which means the scope of this API mechanism is ridiculously large?
  • Each company must use a single unique key?
  • Unclear.
• docs say that <key> is valid for a minimum of 31 days.
  • This is weird, because TTL is usually a specific period, no min or max.
  • Doesn't say how to control the expiration period.
  • Doesn't mention a way to designate a <key> as expired.
  • So does this mean that the expiration of the keys depend on when the key was last used? And has some sort of exponential backoff mechanism to decide the next expiration date?
  • Or that each time a key is used, it's TTL is reset to 31 days?

PSD 2/ Directive (EU) 2015/2366-specific docs

• 3D Secure authentication: https://docs.adyen.com/checkout/3d-secure/
  • For CNP (Card Not Present) transactions
  • v2 being rolled out, complete transition by 2020/21
• Payment essentials: https://docs.adyen.com/payments-essentials/3d-secure-for-regulation-compliance#whatyouneedtoknow

Third-party PSD 2 docs

• Gemalto: PSD2 regulation -- get ready with Gemalto: https://www.gemalto.com/financial/ebanking/psd2
• Ernst & Young PDF whitepaper: https://www.ey.com/Publication/vwLUAssets/Regulatory_agenda_updates_PSDII_Luxembourg/$FILE/Regulatory%20agenda%20updates_PSDII_Lux.pdf

Europa.eu docs

• Payment services (PSD 2) - Directive (EU) 2015/2366: https://ec.europa.eu/info/law/payment-services-psd-2-directive-eu-2015-2366_en
  • Summary of PSD 2: https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=LEGISSUM:2404020302_1&from=EN
  • Actual PSD 2 document: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=celex:32015L2366
  • Amendments to PSD 2: https://ec.europa.eu/info/law/payment-services-psd-2-directive-eu-2015-2366/amending-and-supplementary-acts_en
  • Implementations: https://ec.europa.eu/info/law/payment-services-psd-2-directive-eu-2015-2366/implementation/implementation-eu-countries_en
  • Guidance on implementation and interpretation of EU 2015/2366 (EBA/European Banking Authority guidelines): https://ec.europa.eu/info/law/payment-services-psd-2-directive-eu-2015-2366/implementation/guidance-implementation-and-interpretation-law_en
• Payment Services: re: payment services, SEPA (Single Euro Payments Area), e-mony: https://ec.europa.eu/info/business-economy-euro/banking-and-finance/consumer-finance-and-payments/payment-services_en
• Summary of EU 2015/751 Fees for card-based payments: https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=LEGISSUM:24040603_1&from=EN
• EBA: Regulatory Technical Standards on strong customer authentication and secure communication under PSD2: https://eba.europa.eu/regulation-and-policy/payment-services-and-electronic-money/regulatory-technical-standards-on-strong-customer-authentication-and-secure-communication-under-psd2

Resources

• Generate API key: https://docs.adyen.com/user-management/how-to-get-the-api-key

Glossary

• PED: PIN Entry Device
• ICC: Integrated Circuit Card; i.e. chipped cards.
• DCC: Dynamic Currency Conversion; a quote on currency conversion given by a DCC provider. c.f. https://ap-gateway.mastercard.com/api/documentation/integrationGuidelines/supportedFeatures/pickAdditionalFunctionality/dynamicCurrencyConversion.html?locale=en_US