Skip to navigation

Adyen

View as Markdown

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:

  1. Request API PCI Payments role enablement from Adyen
  2. Generate Adyen API credentials
  3. Confirm your Adyen account uses immediate capture
  4. Connect Adyen to PaymentKit and turn on the payment methods you want
  5. 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:

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:

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.

  1. Log in to your Adyen Customer Area (use the test Customer Area for sandbox)
  2. Navigate to Developers → API credentials
  3. Select (or create) a web-service user, then generate an API key and copy it
  4. 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

  1. Navigate to Orchestration → Payment processors
  2. Click the add (+) button, then choose Adyen from the Payment processor list
  3. Enter a Label for the connection, select the Environment (Sandbox or Production), and enter your API Key and Merchant account
  4. For a Production connection, also enter your Live URL prefix
  5. 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.

  1. In your Adyen Customer Area, navigate to Developers → Webhooks
  2. Click Add webhook and choose Standard webhook
  3. 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 example https://<paymentkit-webhook-domain>/proc_prod_a1b2c3d4e5f6g7h8. Always copy the exact URL from the connect/edit form rather than typing it by hand
  4. 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
  5. Under Security, generate an HMAC Key and copy it (Adyen issues a hex key and signs each notification with HMAC-SHA256)
  6. Under Additional settings, tick Include ARN so each refund’s Acquirer Reference Number reaches PaymentKit and shows on the refund
  7. Save the webhook, and make sure it is enabled
  8. 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.

  1. Download and complete Adyen’s direct debit questionnaire: Adyen direct debit questionnaire.
  2. 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

  1. SEPA is offered only when the payment currency is EUR and your Adyen connection has SEPA enabled with a webhook configured.
  2. 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).
  3. 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.

import PaymentKit from "@payment-kit-js/vanilla";
import SepaPaymentMethod, {
isNonEeaSepaIban,
SEPA_NON_EEA_LINE2_LABEL,
SEPA_NON_EEA_REQUIRED_BILLING_FIELDS,
} from "@payment-kit-js/vanilla/payment-methods/sepa";
const paymentKit = PaymentKit({
environment: "sandbox",
secureToken, // from your backend
paymentMethods: [SepaPaymentMethod /*, ...other methods */],
});

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.

const res = await fetch(`/api/checkout-sessions/token/${secureToken}`);
const session = await res.json();
const processorId = session.bnpl_processors?.sepa; // undefined → no SEPA connection
if (!processorId) {
// No SEPA connection for this session — keep the SEPA pay button disabled.
}

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.

paymentKit.submit({
paymentMethod: "sepa",
fields: {},
options: {
// every value below comes from your own form state
processorId, // session.bnpl_processors.sepa
iban, // raw IBAN; whitespace is stripped for you
ownerName, // account holder
mandateAccepted: true, // required — the customer ticked the mandate
mandateAcceptedAt: new Date().toISOString(), // optional; defaults to now
mandateText, // the exact mandate wording you displayed
mandateVersion, // your mandate template version
customerInfo: {
first_name, last_name, email,
// billing_address ONLY for a non-EEA IBAN (see below)
...(isNonEeaSepaIban(iban) && { billing_address: { line1, line2, city, zip_code, country } }),
},
},
onSuccess: (data) => { /* PROCESSING — not paid. Show a pending state. */ },
onError: (errors) => { /* errors.root = decline/error message; sepa_* keys = field errors */ },
});
OptionRequiredNotes
processorIdYesThe SEPA Adyen connection from session.bnpl_processors.sepa. An empty or missing id fails the charge
ibanYesThe customer’s raw IBAN. Whitespace is stripped for you
ownerNameYesThe bank-account holder’s name
mandateAcceptedYesMust be true — the customer ticked the mandate checkbox
mandateAcceptedAtNoISO-8601 timestamp of acceptance. Defaults to now
mandateTextNoThe exact mandate wording you displayed. Stored as dispute evidence — strongly recommended
mandateVersionNoThe version of your mandate template
customerInfoYesfirst_name, last_name, email (required by the backend, though the SDK type marks them optional); add billing_address for a non-EEA IBAN (see below)

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.

const [sepaName, setSepaName] = useState("");
const [sepaNameTouched, setSepaNameTouched] = useState(false);
// firstName / lastName are your own existing billing-name state.
const billingName = `${firstName} ${lastName}`.trim();
<label htmlFor="sepa-owner">Name on the bank account</label>
<input
id="sepa-owner"
value={sepaNameTouched ? sepaName : billingName}
onChange={(e) => {
setSepaName(e.target.value);
setSepaNameTouched(true);
}}
/>;
// On submit — see "Submit the payment" above for the full options.
paymentKit.submit({
paymentMethod: "sepa",
fields: {},
options: {
ownerName: sepaNameTouched ? sepaName : billingName,
// ...processorId, iban, mandate fields, customerInfo
},
// onSuccess, onError
});

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.

// Re-runs on every IBAN edit. SEPA_NON_EEA_LINE2_LABEL === "House number or name".
{isNonEeaSepaIban(iban) && (
<fieldset>
<input name="line1" required /> {/* street */}
<label htmlFor="line2">{SEPA_NON_EEA_LINE2_LABEL}</label>
<input id="line2" name="line2" required />
<input name="city" required />
<input name="zip_code" required />
<select name="country" required />{/* supply your own country dropdown — PKJS ships none */}
{/* state / region is optional */}
</fieldset>
)}

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 missing
  • sepa_owner_name — the account-holder name is missing
  • sepa_mandate — the mandate was not accepted
  • sepa_billing_<field> — a required non-EEA billing field is missing (for example sepa_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.

By providing your IBAN and confirming this payment, you authorize {creditor_name}, PaymentKit and Adyen (our payment service provider) to send instructions to your bank to debit your account, and your bank to debit your account in accordance with those instructions. This authorizes a one-off debit from your account.
Creditor: {creditor_name}
Creditor identifier: {creditor_identifier}
Account holder: {owner_name}
IBAN: NL •••• •••• 6789
As part of your rights, you are entitled to a refund from your bank under the terms and conditions of your agreement with your bank. A refund must be requested within 8 weeks starting from the date on which your account was debited.

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.