--- title: Adyen API Integration on Truto slug: adyen category: Payment Gateway canonical: "https://truto.one/integrations/detail/adyen/" --- # Adyen API Integration on Truto **Category:** Payment Gateway **Status:** Beta ## Unified APIs ### Unified User Directory API - **Roles** — The Role object represents a role of a User. - **Users** — The User object represents a User. - **Workspaces** — Workspaces represent concepts like teams, workspaces, projects in apps that support them ## How it works 1. **Link your customer's Adyen account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Adyen.** The Proxy API is a 1-to-1 mapping of the Adyen API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Automate payment reconciliation for accounting software** — Accounting and ERP platforms can pull Adyen settlement detail reports to automatically match net payouts against bank feeds, breaking down interchange fees, scheme fees, and Adyen markups into precise ledger entries for their end users. - **Embed payment status and refunds in customer support tools** — Helpdesk and CX platforms can surface real-time Adyen transaction data alongside support tickets and let agents trigger refunds without switching to the Adyen dashboard, reducing resolution time and context-switching. - **Enable sub-merchant onboarding for vertical SaaS platforms** — Booking, marketplace, and vertical SaaS products can automate Adyen for Platforms workflows — creating AccountHolders, managing KYC verification, routing payments to sub-balances, and deducting platform fees — all from within their own product. - **Power off-session recurring payments for billing engines** — Subscription management and billing platforms can retrieve stored Adyen payment tokens tied to their end users' shoppers and trigger server-to-server charges when invoices come due, without requiring the shopper to be present. - **Centralize dispute management across payment providers** — Risk and fraud management SaaS products can ingest Adyen chargeback and dispute data alongside other gateways, giving their end users a single view of defense deadlines, reason codes, and submission workflows. ## What you can build - **Settlement-to-ledger auto-reconciliation** — Automatically pull Adyen settlement detail reports and decompose gross amounts, fees, and net payouts into matching journal entries inside your product. - **Embedded payment status widget** — Display real-time Adyen transaction status, payment method details, and risk scores inline within your application's UI, linked to a shopper's email or reference. - **One-click agent refund flow** — Let end users' support agents initiate full or partial Adyen refunds directly from your product with a single action, without needing Adyen dashboard access. - **Self-serve sub-merchant onboarding portal** — Guide your end users' merchants through Adyen KYC/KYB onboarding, AccountHolder creation, and bank account linking entirely within your platform's dashboard. - **Unified workspace and role mapping for Adyen accounts** — Map Adyen AccountHolders to workspaces and manage user roles and permissions governing who can view settlements, initiate refunds, or manage sub-merchants using Truto's Unified User Directory API. - **Chargeback defense deadline tracker** — Ingest Adyen dispute webhooks and surface chargeback reason codes, current status, and defense due dates so your end users never miss a submission window. ## FAQs ### How does authentication work for the Adyen integration? Adyen uses API keys scoped to merchant accounts or company accounts, along with optional client keys for client-side components. End users generate these credentials in their Adyen Customer Area. Truto securely stores and manages these credentials so your application never handles raw API keys directly. ### Are there specific Truto tools or unified API resources available for Adyen today? Adyen tools are built on request. The Unified User Directory API (Roles, Users, Workspaces) is available and can map Adyen AccountHolders to Workspaces and manage access roles. For payment-specific workflows like refunds, settlements, or dispute management, contact Truto to scope and build the tools you need. ### How does Adyen handle asynchronous payment state changes? Adyen relies heavily on webhooks (notifications) for final payment states. Events like AUTHORISATION, CAPTURE, REFUND, and CHARGEBACK are pushed asynchronously rather than returned synchronously. Any integration should be designed to consume these webhook event codes for accurate status tracking. ### Can I map Adyen's platform hierarchy to Truto's Unified User Directory? Yes. Adyen AccountHolders (sub-merchants) map naturally to Truto Workspaces, and API credentials or shopper references can be represented as Users with Roles that govern permissions like initiating refunds or viewing settlement data. ### What are the rate limits on the Adyen API? Adyen enforces rate limits that vary by endpoint and account tier. High-volume endpoints like Checkout are designed for throughput, but reporting and management APIs may have stricter limits. Truto handles retry logic and pagination so your application doesn't need to manage rate limit responses directly. ### Does Adyen support sandbox or test environments? Yes. Adyen provides a full test environment with separate API keys and endpoints. You can build and validate your integration end-to-end using Adyen's test credentials before going live, and Truto supports connecting to both test and live Adyen environments.