Account-to-account (A2A) payments with iDEAL

Adyen supports making account-to-account (A2A) payments in the Netherlands through iDEAL. This feature allows your users to make online payments using their Adyen business account.

This page explains how to:

• Enable Account-to-Account (A2A) payments directly from Adyen business accounts.
• Retrieve payment details using the /payments/details endpoint.
• Confirm payments using the /payments/confirm endpoint
• Cancel payments using the /payments/cancel endpoint.

Requirements

iDEAL for A2A payments

After you have integrated iDEAL for A2A payments, business account users can select iDEAL as a payment method during checkout. The payment flow redirects users to your platform, where they select their Adyen business account, complete a Strong Customer Authentication (SCA) process, and then authorize the payment.

For platforms, this means faster payments, fewer dependencies on external banks, and a smoother user experience.

How users complete SCA using your platform

To complete the checkout process, your user must use your platform to complete SCA. How your user completes SCA depends on the device that they are using:

Redirection

Users are redirected from the checkout to your platform's app or website to authorize the payment. The user flow is as follows:

Mobile (App-to-app)

1. The user starts the checkout on their mobile device, the mobile browser displays a "Select your bank" screen.
2. The user must select Adyen from the list, followed by selecting your platform.
3. The mobile browser opens your platform's app.
4. The user authorizes the payment within your app and is then automatically redirected back to the checkout in their mobile browser.

Desktop computer

1. The user starts the checkout on their desktop computer, the desktop browser displays a "Select your bank" screen.
2. The user selects Adyen from the list of banks on their desktop browser, followed by selecting your platform.
3. The desktop browser opens your platform's web login page.
4. The user authorizes the payment on the web page and is then automatically redirected back to the checkout in their desktop browser.

QR scan

Users scan an iDEAL QR code on their desktop to authorize the payment via your mobile app. The user flow is as follows:

Desktop computer

1. The user scans the iDEAL QR code displayed in the desktop browser using the QR reader within their mobile app.
2. This transfers the authorization session from the desktop computer to the mobile device.
3. After authorizing the payment, your mobile app must only show a success or confirmation screen.
4. Do not redirect the user from the mobile app to the checkout page. The desktop browser automatically detects the completed payment and handles the redirection to the checkout page.

How it works

The typical iDEAL integration flow with Adyen is as follows:

1. Checkout: The user initiates an iDEAL payment at the checkout page.
2. Select bank: The user is presented with an iDEAL screen where they can choose to scan a QR code or select a bank. If they choose to select a bank, they must select Adyen from the list of banks.
3. Select platform: The user is redirected to a platform selection page, located at the payment_redirect_url you provided in the configure required redirect URLs step. From there, they must choose your platform from a list of all supported options. To automate this process, you can have users scan a QR code from your app.
4. Log in: The user must authenticate themselves on your platform.
5. Show details: The user is shown the details of the payment, prompted to authorize the transaction, and potentially select a source balance account (if multiple exist).
6. Authorize: The user authorizes the payment using Strong Customer Authentication (SCA).
7. Result: Upon successful payment or cancellation, the user is redirected back to the platform's page. The specific URL for this final redirection is returned by the /payments/confirm endpoint for success cases and the /payments/cancel endpoint for cancellations. The platform then displays the payment outcome, such as "Payment successful" to the user.

The following tabs show example images of the screens that the user sees at each step of the flow.

Integration steps

Follow these steps to implement an iDEAL integration:

1. Configure required redirect URLs
2. Retrieve payment information
3. Check SCA eligibility
4. Initiate SCA payment confirmation
5. Authenticate user
6. Complete SCA payment confirmation
7. Cancel a payment
8. iDEAL profile endpoints

Configure required redirect URLs

To enable redirection for A2A payment and authentication to your platform, you must configure redirect URLs on your platform.

1. Configure the following redirect URLs on your platform:

   • payment_redirect_url: This is where Adyen sends users after they select your platform from Adyen's platform selection page. This URL should be configured to:

     • Require the user to log in with their credentials.
     • Accept a payload query parameter, which is then used in the /payments/details endpoint.
     • Redirect the user to a payment page that displays the transaction details for authorization.

   • authenticate_redirect_url: Adyen will use this URL to redirect the user to your platform if iDEAL requests user authentication. For details, see the iDEAL profile authenticate endpoint section.

2. Provide the specific URLs for these endpoints to Adyen as part of your integration setup.

   Both redirect URLs must support HTTPS and be capable of handling query parameters containing transaction context.

Retrieve payment information

Retrieve the iDEAL transaction information before authorization begins. This is done in two situations: after the user scans the payment QR code, or after they are redirected to your payment_redirect_url and have logged in.

1. From your server, make a POST /payments/details request specifying the following parameters:

   Parameter	Location	Required	Applies to	Description
   method	Body		All	The payment method this payment is from. Set to ideal.
   source	Body		method: ideal	The source that was used to obtain the payload. Possible values include redirect or qr.
   payload	Body		method: ideal	The payment payload is an identifier for the payment. It's generated by iDEAL and provided in two ways: as the content of a QR code or as a query parameter during a redirect.

   The following example shows a request for retrieving transaction information.

2. In the response, note the token and other transaction details. You will need this token in the confirm a payment or cancel a payment step. The response also contains the specific details of the transaction. See the details in the following fields:

   Parameter	Description
   token	A unique, short-lived identifier for a pending transaction. Its validity period depends on the payment provider; for iDEAL, it's typically around 15 minutes. It is used to reference the specific payment in subsequent /payments/confirm or /payments/cancel endpoint requests.
   value	The numerical value of the amount.
   currency	Currency of a monetary amount.
   counterparty	An object containing information about the counterparty that will receive the funds.
   counterparty.accountHolder	Details about the account holder who will receive the funds.
   fullName	The full name of the counterparty's account holder.
   type	The type of account identification.
   iban	The IBAN of the bank account.
   description	A description of the transaction.
   expiresAt	The timestamp when the transaction token expires.

If you encounter any errors, see error codes and messages.

Check SCA eligibility

Before confirming the payment, first check device eligibility. The following tabs explain how to check for SCA eligibility and initiate authentication using Kotlin, Swift, or JavaScript.

You will use the sdkOutput when confirming the payment.

Initiate SCA payment confirmation

Confirm a payment using the token that you obtained when you retrieved the payment information. The operation is secured by Strong Customer Authentication (SCA).

1. Make an initial POST /payments/confirm request specifying the following parameters:

   Parameter	Location	Required	Description
   WWW-Authenticate	Header		SCA realm: A2APayment. auth-param1: Value of sdkOutput from the Check SCA eligibility step.
   token	Body		A unique, short-lived identifier for a pending transaction. Its validity period depends on the payment provider; for iDEAL, it's typically around 15 minutes. It is used to reference the specific payment in subsequent /payments/confirm or /payments/cancel endpoint requests.
   balanceAccountId	Body		Balance account ID of the account where the funds should be substracted. For example, BA00000000000000000000000.

2. The API returns a HTTP 401 - Unauthorized response with the message "User needs to perform SCA." The response headers include the following parameters:

   Parameter	Description
   WWW-Authenticate	The header containing the SCA challenge.
   auth-param1	An attribute within the WWW-Authenticate header that holds the sdkInput value.
   sdkInput	The SCA challenge that you must pass to the user's device for authentication.

   Here is an example of the response header:

3. Pass auth-param1 to the SDK as sdkInput.

Authenticate user

To authenticate your user with the Authentication SDK:

1. Trigger the SDK to start user authentication and pass the auth-param1 value from the previous step as sdkInput.

2. Pass sdkOutput to your server.

You will use the sdkOutput when completing the payment confirmation.

Complete SCA payment confirmation

After completing the SCA challenge, you can finalize the payment by sending a POST request to the /payments/confirm endpoint. This request submits the sdkOutput from the solved challenge confirming the transaction.

1. Make a second POST /payments/confirm request specifying the following parameters:

   Parameter	Location	Required	Description
   WWW-Authenticate	Header		SCA realm: A2APayment. auth-param1: Value of sdkOutput from the Authenticate user step.
   token	Body		A unique, short-lived identifier for a pending transaction. Its validity period depends on the payment provider; for iDEAL, it's typically around 15 minutes. It is used to reference the specific payment in subsequent /payments/confirm or /payments/cancel endpoint requests.
   balanceAccountId	Body		Balance account ID of the account where the funds should be substracted. For example, BA00000000000000000000000.

2. Verify that the response contains a success object indicating the transaction was successful, which contains the related links. See the details in the following fields:

   Parameter	Description
   links	An object containing one or more links related to the next steps in the payment flow.
   success	An object containing the URL that the user should be redirected to in order to complete the "success" path of the payment confirmation.
   href	The URL string to which the user should be redirected.

   For QR code flows initiated on a desktop computer, do not redirect the user from the mobile app back to the platform. The desktop browser automatically detects the completed payment and handles the redirection to the checkout page.

If you encounter any errors, see error codes and messages.

Cancel a payment

Use the /payments/cancel endpoint to cancel a pending payment that has not yet expired or been confirmed. A payment is considered canceled when the redirectUrl in the API response is opened.

1. Make a POST /payments/cancel request specifying the following parameters:

   Parameter	Location	Required	Description
   token	Body		A unique, short-lived identifier for a pending transaction. Its validity period depends on the payment provider; for iDEAL, it's typically around 15 minutes. It is used to reference the specific payment in subsequent /payments/confirm or /payments/cancel endpoint requests.

2. The response for a successful cancellation contains a links object. This object has a cancel field, which includes a href property that specifies a redirect URL. See the details in the following fields:

   Parameter	Description
   links	An object containing one or more links related to the next steps in the payment flow.
   cancel	An object containing the URL that the user should be redirected to in order to complete the "cancel" path of the payment.
   href	The URL string to which the user should be redirected.

If you encounter any errors, see error codes and messages.

Payment screen requirements

All screens related to the iDEAL flow (payment, profile, and authentication) must comply with iDEAL's UX and regulatory standards. To comply with these standards, your screens must display the following:

• iDEAL/WERO logo: show the iDEAL logo clearly on all screens to indicate the transaction is using iDEAL as the payment method.
• Amount and currency: the full payment amount and currency.
• Payee (recipient): clearly identify who is recieving the payment.
• Payment description: include a brief, user-friendly description of the transaction.
• Account switch option: let users switch balance accounts if needed.
• Confirmation screen with result: For example, in case of success, display a confirmation screen should display with all the transaction details again. These details must include the selected bank account (in IBAN format), the iDEAL payment method, amount and currency, and description.

Design

Adyen requires early access to the wireframes for the iDEAL flow screens within your app or web application. Share these with your Adyen contact as soon as they are available and before you go live, so that they can be validated and you can be informed of any necessary changes early in your development process.

iDEAL profile endpoints

As an optional feature, you can allow users to create and manage their iDEAL profiles. This lets them securely store payment and delivery information, enabling them to make future payments with a single click.

These endpoints are not required for standard iDEAL payment processing but provide a way to interact with the profile management features, offering a faster and more convenient checkout experience for your users. For more details, see the iDEAL Profile FAQ.

Create an iDEAL profile

To create a new iDEAL profile:

1. Make a POST /ideal/profile/register request specifying the following parameters:

   Parameter	Required	Description
   accountHolderId		The unique identifier for an account holder.
   paymentInstrumentIds		The IDs for the payment instruments to be associated with the iDEAL profile.

2. The response includes a redirectUrl object with href property. This href specifies a redirect URL. See the details in the following fields:

   Parameter	Description
   redirectUrl	A short-lived URL that redirects the user to the iDEAL profile registration page. You must redirect the user to this URL within 5 seconds of receiving the response.
   href	The URL string to which the user should be redirected.

3. Select the href URL and follow the steps to create your iDEAL profile.

Generate a profile management URL

The iDEAL profile management page allows your users to edit their iDEAL profile. For example, they can manage personal details, linked accounts, and delivery addresses, or view trusted webshops. They can also use this page to delete their profile entirely.

To generate a URL for your user's iDEAL profile management page:

1. Make a POST /ideal/profile/auth-link request specifying the following parameters:

   Parameter	Required	Description
   accountHolderId		The unique identifier for an account holder.

2. The response includes a redirectUrl object with href property. This href specifies a redirect URL. See the details in the following fields:

   Parameter	Description
   redirectUrl	A short-lived URL that redirects the user to the iDEAL profile registration page. You must redirect the user to this URL within 5 seconds of receiving the response.
   href	The URL string to which the user should be redirected.

Authenticate

To generate a URL after a user has been authenticated, typically via Multi-Factor Authentication (MFA) use the /ideal/profile/authenticate endpoint. This is used for actions such as changing profile details or to unmask sensitive payment information.

1. Make a POST /ideal/profile/authenticate request specifying the following parameters:

   Parameter	Required	Description
   accountHolderId		The unique identifier for an account holder.
   payload		A payload initiated by iDEAL to complete the authentication process. It's generated by iDEAL and provided in two ways: as the content of a QR code or as a query parameter during a redirect.

2. The response includes a redirectUrl object with href property. This href specifies a redirect URL. See the details in the following fields:

   Parameter	Description
   redirectUrl	A short-lived URL that redirects the user to the iDEAL profile registration page. You must redirect the user to this URL within 5 seconds of receiving the response.
   href	The URL string to which the user should be redirected.

Error codes and messages

These are the common error codes. See the descriptions below for details.

A2A payment errors

iDEAL profile errors

See also