Adyen API Integration Guide
A developer reference for integrating Adyen's unified payments platform. Covers Drop-in and API-only integration approaches, supported payment methods, recurring payments, 3DS2 native flow, split payments for marketplaces, and RevenueProtect risk management.
Integration Approaches
Adyen provides three integration paths, each balancing UI control against implementation effort and PCI scope. All approaches use the same Checkout API (/v71/payments and /v71/payments/details) on the backend.
| Approach | Description | UI Control | PCI Scope | Best For |
|---|---|---|---|---|
| Drop-in | Pre-built UI component that renders all available payment methods with built-in 3DS2, redirects, and validation. | Minimal -- Adyen provides the UI | SAQ A (card fields in Adyen iframe) | Fast integration with many payment methods and minimal frontend work |
| Components | Individual UI components per payment method. Rendered in your layout, Adyen handles sensitive input fields. | Moderate -- you arrange components in your design | SAQ A (card fields in Adyen iframe) | Custom checkout layouts while keeping PCI scope minimal |
| API-only | Direct API calls with your own UI. You build all form elements and submit encrypted card data or payment method details. | Full -- you build every UI element | SAQ A-EP or SAQ D (depending on implementation) | Complete design control, native mobile apps, server-to-server flows |
Supported Payment Methods
Adyen supports over 250 payment methods globally. Enable methods per merchant account in the Customer Area, then query available methods for a given transaction via POST /v71/paymentMethods, which returns methods filtered by currency, amount, country, and shopper locale.
| Method | Regions | Settlement | Notes |
|---|---|---|---|
| Cards | Global | T+1 to T+3 | Visa, Mastercard, Amex, Discover, JCB, UnionPay |
| Apple Pay | Global (Apple devices) | T+1 to T+3 | Requires Apple Pay merchant ID and domain verification |
| Google Pay | Global (Android, Chrome) | T+1 to T+3 | Requires Google Pay merchant ID |
| iDEAL | Netherlands | T+1 | Bank redirect, returns are synchronous |
| Bancontact | Belgium | T+1 | Bank redirect with optional mobile app flow |
| SEPA Direct Debit | EU / EEA | T+5 to T+14 | Requires mandate, supports recurring |
| Klarna | EU, US, AU | T+1 to T+3 | Pay now, pay later, or installments |
| Boleto | Brazil | T+1 to T+3 (after payment) | Voucher-based, async confirmation |
| PIX | Brazil | Instant | QR code or copy-paste, 24/7 availability |
| PayPal | Global | Immediate to PayPal, T+1 to bank | Redirect flow with express checkout option |
Recurring Payments
Adyen supports tokenization for recurring and one-click payments. When a shopper pays for the first time, include storePaymentMethod: true and a shopperReference in the payment request. Adyen returns a recurringDetailReference (token) for subsequent charges.
Recurring payment types differ in SCA requirements:
- CardOnFile: Shopper-initiated, stored card. SCA applies on first use; subsequent use may be exempt.
- Subscription: Merchant-initiated, fixed schedule. SCA on initial setup only; subsequent charges are MIT-exempt.
- UnscheduledCardOnFile: Merchant-initiated, variable timing. SCA on initial setup; subsequent charges with MIT exemption flag.
3DS2 Native Flow
Adyen's native 3DS2 implementation collects device fingerprint data and sends it to the issuer for risk-based authentication. The flow operates in two stages:
- Fingerprint (frictionless): The Drop-in or Component collects browser data and sends it to the issuer. If the issuer approves based on the fingerprint, the payment completes without shopper interaction.
- Challenge: If the issuer requires additional verification, a challenge window appears (embedded or redirect). The shopper completes authentication (OTP, app approval, biometric), and the result is submitted via
/payments/details.
For API-only integrations, you must implement the fingerprint collection and challenge rendering yourself using the data returned in the action object of the payments response.
Split Payments for Marketplaces
Adyen for Platforms (formerly MarketPay) enables marketplaces to split a single payment across multiple parties. Each split is defined in the splits array on the payment request, specifying the amount, account, type, and reference for each recipient.
Split types include BalanceAccount (sub-merchant receives funds), Commission (platform commission), and Remainder (catch-all for unallocated amounts). Platforms can also hold funds in a liable balance account before releasing to sellers.
Risk Management (RevenueProtect)
RevenueProtect is Adyen's built-in risk engine. It evaluates every transaction using customizable rules, velocity checks, and machine learning models. Key capabilities:
- Risk scoring: Each transaction receives a 0-100 risk score. Configure thresholds to block, review, or allow.
- Custom rules: Define rules based on transaction attributes (amount, country, email domain, device fingerprint, shopper history).
- Velocity checks: Rate-limit transactions by card, email, IP, or shopper reference within configurable time windows.
- Referral management: Route flagged transactions to a manual review queue in the Customer Area.
- Dispute management: Automated chargeback handling, pre-arbitration responses, and fraud reporting.
Send additional data fields (riskData, shopperIP, deliveryAddress) in payment requests to improve risk model accuracy.
Disclaimer: This guide is an independent technical reference and is not affiliated with or endorsed by Adyen N.V. API specifications, payment method availability, and features are subject to change. Always consult the official Adyen documentation for the most current information.