Create a legal entity for the seller via POST /legalEntities with type=individual (for sole traders) or type=organization (for businesses), providing required identification fields — the legal entity ID is the root resource for all subsequent KYC.
Create an account holder via POST /accountHolders specifying legalEntityId and requesting the capabilities you need (e.g., receivePayments, receiveFromPlatformPayments, sendToTransferInstrument) — capability status starts as inactive pending KYC.
Create a balance account and link it to the account holder via POST /balanceAccounts with accountHolderId; this is where split payment proceeds will land.
Generate a hosted onboarding link via POST /accountHolders/{id}/onboardingLinks and redirect the seller to this URL to complete KYC; Adyen collects documents and verifies identity asynchronously.
Subscribe to the balancePlatform.accountHolder.updated webhook and check the capabilities object in the payload — when sendToTransferInstrument transitions to active (verificationStatus=valid), the seller's balance account is eligible to receive payouts.
Add the seller's verified bank account as a transfer instrument via POST /transferInstruments with type=bankAccount and link it to the account holder; this enables payout sweeps to the seller's external bank.
Known gotchas
Adyen's KYC is asynchronous — the onboarding link submission completes quickly but verification processing can take minutes to hours; do not assume capability activation at onboarding link completion; rely exclusively on the webhook event.
Different countries have different KYC document requirements managed by Adyen's verification rules; missing a country-specific required field causes the verification to enter a PENDING_INFORMATION state — use Adyen's KYC Insights dashboard (updated daily at 03:00 CET) to monitor stuck onboardings.
Legal entities and account holders are separate objects — deleting or modifying a legal entity does not automatically update linked account holders; maintain a mapping in your own database to manage the relationship.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp