Adyen
Accept card and SEPA Direct Debit payments through Adyen using PaymentKit. PaymentKit handles PCI compliance and securely orchestrates every payment operation with Adyen — 3D Secure, network tokens, off-session subscription renewals, refunds, and SEPA (euro bank debit), including its mandate and asynchronous settlement flow.
Set up summary
To accept payments with Adyen in PaymentKit, you will need to:
- Request API PCI Payments role enablement from Adyen
- Generate Adyen API credentials
- Confirm your Adyen account uses immediate capture
- Connect Adyen to PaymentKit and turn on the payment methods you want
- Configure an Adyen standard webhook and add its HMAC signing key to PaymentKit (required for refunds and SEPA)
Request API PCI Payments role enablement
PaymentKit routes payments to Adyen, but Adyen will reject all card charges until the API PCI role is enabled on your account. This role is required if you or a Third-Party Service Provider (TPSP) handle raw, unencrypted card data. To allow PaymentKit to process your payments, submit a one-time activation request to Adyen’s Payment Risk Operations team (paymentriskoperations@adyen.com).
Here are all the docs you will need to share with Adyen when submitting your request:
- PaymentKit ASV Site Certification Attestation
- PaymentKit Compliance Certificate
- PaymentKit Self-Assessment Questionnaire (SAQ D-SP)
- VGS PCI DSS documentation
- PCI DSS document (SAQ A) — to be downloaded and completed by you before sending to Adyen
Submit a request to paymentriskoperations@adyen.com using the following message:
Hi,
We’d like to activate the API PCI Payments role on our account:
{{WS_username}}.PaymentKit serves as our PCI-compliant payment orchestrator and provides the required Self-Assessment Questionnaire (SAQ D) and On-Site Attestation of Compliance, which can be accessed at the following links:
- PaymentKit ASV Site Certification Attestation
- PaymentKit Compliance Certificate
- PaymentKit Self-Assessment Questionnaire (SAQ D-SP)
Raw card data is handled by our PCI DSS-compliant third-party service provider, Very Good Security (VGS), which vaults and tokenizes card data on our behalf. As a payment orchestrator, we route either VGS-provisioned network tokens or raw PANs depending on the flow; VGS handles the raw card data in both cases. VGS’s PCI DSS documentation can be found here.
We’ve also attached our completed PCI DSS self-assessment questionnaire (SAQ A) listing PaymentKit and VGS as TPSPs.
Replace {{WS_username}} with your Adyen web-service (API) username. You must also fill out the PCI DSS document (SAQ A) before you send it to Adyen with your request.
What Adyen supports in PaymentKit
PaymentKit supports the following with Adyen:
- Card payments — one-time and customer-initiated (CIT)
- Off-session / merchant-initiated payments (MIT) — including subscription renewals and dunning retries
- 3D Secure 2 (3DS2) — both the frictionless and challenge flows
- Network tokens
- Refunds — see Refunds below
- SEPA Direct Debit — euro bank debit; see How SEPA Direct Debit works below
The following is not currently supported:
- Manual capture / authorization holds (immediate capture only — see below)
- Partial capture
- Digital wallets (Apple Pay and Google Pay)
- Adyen local payment methods
- ACH direct debit
For non-euro bank debit or any of the methods above, use a different processor.
Generate API credentials in Adyen
PaymentKit requires an API key and your merchant account name to securely connect to your Adyen account.
- Log in to your Adyen Customer Area (use the test Customer Area for sandbox)
- Navigate to Developers → API credentials
- Select (or create) a web-service user, then generate an API key and copy it
- Note your merchant account name — shown in the Customer Area account switcher
For a production connection, Adyen assigns your account a unique live URL prefix. Find it in the Customer Area under Developers → API URLs. PaymentKit needs this prefix to reach your live Adyen endpoints — sandbox connections do not require it.
A cards-only connection needs only these values: API key, merchant account, and the environment (plus the live URL prefix in production). The webhook HMAC key described later is required for refund settlement and for SEPA.
Set your Adyen account to immediate capture
Your Adyen account — and the merchant account you connect — must be configured for immediate (instant) capture. This integration does not support manual or delayed capture.
With manual or delayed capture, PaymentKit’s charges are only authorized at Adyen and never captured. The payment appears successful, but any later refund will fail — Adyen returns “Transaction hasn’t been captured, refund not possible.”
In your Adyen Customer Area, set your capture delay / capture mode to immediate before you start accepting live payments.
Connect Adyen to PaymentKit
- Navigate to Orchestration → Payment processors
- Click the add (+) button, then choose Adyen from the Payment processor list
- Enter a Label for the connection, select the Environment (Sandbox or Production), and enter your API Key and Merchant account
- For a Production connection, also enter your Live URL prefix
- Turn on the payment methods you want to accept
SEPA Direct Debit cannot be enabled until you add the webhook HMAC signing key (next step). SEPA payments settle asynchronously, and PaymentKit can only confirm them from a signed Adyen webhook — without the signing key those outcomes could never be verified, so SEPA stays unavailable.
Configure the Adyen webhook and HMAC key
Set up a standard webhook in Adyen so PaymentKit can receive asynchronous notifications.
Card authorization and capture happen synchronously — cards work without a webhook configured. A webhook is required for refund settlement and for SEPA, both of which are asynchronous.
- In your Adyen Customer Area, navigate to Developers → Webhooks
- Click Add webhook and choose Standard webhook
- Under Server configuration, paste the webhook URL shown on your Adyen connection in PaymentKit. It is unique per connection and ends with your connection’s ID (a
proc_…value) — for examplehttps://<paymentkit-webhook-domain>/proc_prod_a1b2c3d4e5f6g7h8. Always copy the exact URL from the connect/edit form rather than typing it by hand - Enable the REFUND event so refund outcomes are delivered. If you accept SEPA, also enable the AUTHORISATION event — that is the notification that settles a SEPA charge
- Under Security, generate an HMAC Key and copy it (Adyen issues a hex key and signs each notification with HMAC-SHA256)
- Under Additional settings, tick Include ARN so each refund’s Acquirer Reference Number reaches PaymentKit and shows on the refund
- Save the webhook, and make sure it is enabled
- Back in PaymentKit, edit your Adyen connection and paste the key into the Webhook HMAC key field
Enable HMAC signing on the webhook and use the same key in both places. PaymentKit verifies every incoming notification’s signature with this key and ignores any notification that does not match — so a missing or mismatched key means refund and SEPA outcomes never settle.
Keep the webhook enabled in Adyen for as long as you accept SEPA or process refunds. If it is disabled or misconfigured, Adyen stops delivering results — the affected refunds stay pending and SEPA payments stay processing indefinitely.
Refunds
Adyen refunds are asynchronous. When you issue a refund, PaymentKit sends it to Adyen and records it as pending; it resolves to succeeded only once Adyen confirms it with a REFUND webhook notification.
If you have not configured the webhook and its HMAC key, a refund still executes at Adyen, but PaymentKit has no way to learn the outcome — so the refund stays pending in PaymentKit indefinitely. Configure the webhook (above) before processing refunds.
How SEPA Direct Debit works
SEPA Direct Debit lets euro-zone customers pay directly from their bank account instead of using a card. It behaves differently from card payments, so it helps to set expectations for both you and your customers.
The webhook HMAC key is required to enable SEPA. Because SEPA settles asynchronously, PaymentKit will not offer or charge SEPA on a connection that has no HMAC key configured.
Request SEPA enablement
Before you can accept SEPA Direct Debit, Adyen must enable it on your merchant account. Adyen reviews each request, so complete this step ahead of when you plan to go live.
- Download and complete Adyen’s direct debit questionnaire: Adyen direct debit questionnaire.
- Email support@adyen.com with your completed questionnaire attached, using the request below.
Hi,
We’d like to enable SEPA for our account:
{{WS_username}}.We’ve attached our completed direct debit questionnaire.
Thank you.
Fill out the direct debit questionnaire and attach it before you send the request —
Adyen cannot enable SEPA without it. Replace {{WS_username}} with your Adyen
web-service (API) username (the web-service user from
Generate API credentials in Adyen).
Adyen typically responds within a few business days. Once SEPA is enabled on your account, turn it on for your Adyen connection in PaymentKit.
At checkout
- SEPA is offered only when the payment currency is EUR and your Adyen connection has SEPA enabled with a webhook configured.
- The customer enters their IBAN and account-holder name, and accepts a mandate — their authorization for you to debit the account. For a subscription, the mandate also authorizes future renewals; for a one-time payment, it authorizes a single debit only. If the IBAN is from a SEPA country outside the EEA, the checkout also asks for a billing address (see Billing address for non-EEA IBANs).
- The payment is submitted to Adyen, which normally accepts the debit instruction and returns a processing result — not a final “paid”. (A submission Adyen cannot accept — for example a malformed IBAN — is declined immediately at checkout instead.)
Billing address for non-EEA IBANs
A few SEPA countries are outside the EEA. When a customer pays with an IBAN issued in one of them, Adyen requires a full billing address on the payment and rejects it without one (error 194, “Billing address missing”). IBANs issued inside the EEA do not need an address — nothing changes for them.
The country is set by the IBAN’s first two letters. The non-EEA SEPA countries are the United Kingdom and Switzerland, plus Albania, Andorra, Moldova, Monaco, Montenegro, North Macedonia, San Marino, Serbia, and Vatican City (a UK IBAN also covers Guernsey, the Isle of Man, and Jersey).
On the hosted checkout this is automatic. When the customer enters a non-EEA IBAN, the checkout reveals and requires a billing-address block, whatever your other checkout settings. An EEA IBAN adds no address requirement of its own — the checkout then collects an address only if your normal checkout settings already do, which by default they do. You do not need to do anything.
In a non-EEA SEPA billing address, the second address line is the house number or name (Adyen reads the house number from it), so the checkout labels it that way. A state or region is not required.
Settlement is asynchronous
Money physically moves through the banking system, so the final result arrives later — typically within a few minutes in test, and anywhere from minutes to a few business days in production. Until it does:
- The payment shows as processing, not paid.
- The related invoice stays open.
- A new subscription stays incomplete — it is not activated yet, and no confirmation email is sent.
When the bank result arrives via the Adyen webhook:
- Success → the payment and its invoice are both marked paid, any subscription activates and its mandate is stored for future renewals, and the success receipt is sent.
- Failure (for example insufficient funds or a closed account) → the payment is marked failed and your normal dunning / decline handling runs.
A processing SEPA payment is normal and expected — it does not mean anything went wrong. Unlike a card authorization that resolves instantly, bank debit is inherently asynchronous. Avoid granting access or shipping goods until the payment reaches paid.
SEPA refunds
SEPA refunds are asynchronous too. When you refund a settled SEPA payment, the refund is recorded as pending and resolves to succeeded — or failed if the bank rejects it — once Adyen confirms the outcome via webhook.
SEPA Direct Debit is EUR-only. A SEPA payment in any other currency is rejected before it reaches Adyen. Use a card processor for non-euro charges.
Integrate SEPA with PaymentKit.js
The hosted checkout handles SEPA for you — if you use it, there is nothing to build and you can skip this section. Read on only if you build an embedded checkout with PaymentKit.js.
PaymentKit.js mounts no elements or iframes for SEPA. Your page renders every input itself — an IBAN field, an account-holder name field, a mandate checkbox showing the mandate text, and (for a non-EEA IBAN) a billing-address block — then submits through paymentKit.submit. The IBAN is bank data, sent directly with no VGS tokenization, unlike the card number.
Register the SEPA method
SEPA is imported from its own subpath — NPM / bundler only.
There is no PaymentKit.PaymentMethods.sepa. Import SepaPaymentMethod from
@payment-kit-js/vanilla/payment-methods/sepa and add it to paymentMethods. SEPA is
not available through the CDN <script> global today — use an NPM / bundler build.
Get the SEPA processor id from the session
SEPA is routed on the front end, like BNPL. Fetch your checkout session — GET /api/checkout-sessions/token/{secureToken} — and read session.bnpl_processors.sepa (the raw JSON field; the generated SDK client exposes it camelCased, as session.bnplProcessors.sepa). That value is your processorId. If it is absent, this session has no SEPA connection — disable or hide the pay button. The SDK types mark processorId optional, but SEPA has no routing fallback (unlike cards): always resolve and send it, or the charge fails with no credentials to resolve.
Submit the payment
Submit with paymentMethod: "sepa". The callbacks are siblings of options. fields is ignored for SEPA — the customer’s identity goes in options.customerInfo.
Behind the scenes the SEPA method posts to an internal Adyen SEPA start endpoint. You
never call it directly — always go through paymentKit.submit.
Prefill the account-holder name
Your checkout almost certainly already collects a billing name, so the SEPA account-holder name (ownerName) is a second name field — double entry for a customer typing by hand. PaymentKit.js renders no SEPA inputs, so it cannot see your other fields and does not prefill anything: the account-holder input is your input, and the prefill is your code.
Seed it from your billing name as an editable default — keep the field visible and editable, and stop overriding it once the customer edits it. A touched flag does this: prefill until the customer types, then leave their value alone.
Keep this field editable, and never submit the billing name as ownerName silently.
The account-holder name must match the name on the bank account, which is not
always the billing contact — joint accounts, business accounts, or someone paying for a
family member all differ. If the customer clears the field, let the submit proceed:
PaymentKit.js returns sepa_owner_name: "required", which you map to an inline error like
any other field error (see PaymentKit.js re-validates at submit).
(Browser autofill may already fill both on its own, so this mainly helps customers who type.)
Collect a billing address for non-EEA IBANs
A few SEPA countries sit outside the EEA, and Adyen requires a full billing address for an IBAN issued in one of them. Call isNonEeaSepaIban(iban) reactively, as the customer types the IBAN, and reveal a billing-address block when it returns true. SEPA_NON_EEA_LINE2_LABEL is the label text to use for that block’s line-2 input — for a non-EEA SEPA address, line 2 is the house number or name, not a second street line.
The required fields are line1, line2, city, zip_code, and country — also exported as the array SEPA_NON_EEA_REQUIRED_BILLING_FIELDS (["line1", "line2", "city", "zip_code", "country"]) if you would rather drive your form from the list. State or region is not required. Send them as customerInfo.billing_address on submit (shown above).
For the exact list of non-EEA SEPA countries, see Billing address for non-EEA IBANs.
PaymentKit.js re-validates at submit
Even if your form skips a check, PaymentKit.js re-validates at submit and returns field errors to onError without any network call. Each key has the value "required":
sepa_iban— the IBAN is missingsepa_owner_name— the account-holder name is missingsepa_mandate— the mandate was not acceptedsepa_billing_<field>— a required non-EEA billing field is missing (for examplesepa_billing_line1)
Map these keys back to your inputs to show inline errors.
A decline or an error response from the server resolves onError with { root, sepa } — both hold the same customer-facing message. A network failure or other thrown error resolves it with only { root }. Either way, render errors.root.
SEPA results are asynchronous
onSuccess for SEPA means the debit was accepted and is now processing — it does not mean paid. Its data carries paymentIntentId, checkoutAttemptId, checkoutSessionId, state: "payment_started", and charge_status: "pending" — record it so you can reconcile against the later webhook outcome. Render a processing state and wait for the final result from the Adyen webhook; see Settlement is asynchronous. An immediate decline — for example a malformed IBAN — comes back through onError instead.
You own the mandate
You render the mandate text and pass mandateText and mandateVersion. PaymentKit stores the text, a hash of it, and the acceptance IP and user-agent as dispute evidence. Whether the mandate is reusable (for subscription renewals) or one-off is decided automatically from the checkout — a subscription or setup session versus a one-time payment — so it is not a flag you set.
You do not have to write a mandate from scratch — adapt the one PaymentKit’s own checkout uses. Fill the creditor details from session.sepa_mandate_info (creditor_name, creditor_identifier, and optional creditor_address), show the account holder, and mask the IBAN to its country prefix and last four digits. Keep the refund clause verbatim.
For a subscription or setup session, replace the one-off sentence with: “Because this is a subscription, RECURRING debits may be taken from your account on an ongoing basis for future payments until you cancel.” Pass the exact text you displayed as mandateText, and bump mandateVersion whenever you change the wording.