Accept iDEAL payments

Use the JavaScript SDK to render payment fields and buttons and process payments with the Orders API.

Buyer experience

Note: The payment button is disabled in the buyer experience demo. On button click, the user is redirected to their bank to authorize the transaction.

Know before you code

Note: Partners need to onboard merchants upfront before they accept payments. iDEAL doesn't support onboarding after making payments, specifically Progressive Onboarding. 

• Use Postman to explore and test PayPal APIs.

1. Add PayPal JavaScript SDK

Add or update the JavaScript SDK script on your web page.

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=buttons,payment-fields,marks,funding-eligibility&enable-funding=ideal&currency=EUR"></script>

This table lists the parameters you pass to the JavaScript SDK.

See additional, optional parameters.

2. Render payment mark

You can use a mark integration for payment fields components to present the payment method options to the buyer as radio buttons.

paypal
  .Marks({
    fundingSource: paypal.FUNDING.IDEAL,
  })
  .render("#ideal-mark");

3. Render payment fields

Use payment fields to collect payment information from buyers. Fields dynamically render based on the selected funding source and you can customize the fields to align with your brand.

Choose from a single page checkout flow or a multi-page checkout flow.

paypal
  .PaymentFields({
    fundingSource: paypal.FUNDING.IDEAL,
    /* style object (optional) */
    style: {
      /* customize field attributes (optional) */
      variables: {},
      /* set custom rules to apply to fields classes (optional) */
      rules: {},
    },
    fields: {
      /* fields prefill info (optional) */
      name: {
        value: "Firstname Lastname",
      },
    },
  })
  .render("#ideal-container");

For style parameters, please reference this style page: Custom style for payment fields

4. Render payment button

paypal
  .Buttons({
    fundingSource: paypal.FUNDING.IDEAL,
    style: {
      label: "pay",
    },
    createOrder() {
      return fetch("/my-server/create-paypal-order", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        // use the "body" param to optionally pass additional order information
        // like product skus and quantities
        body: JSON.stringify({
          cart: [
            {
              sku: "YOUR_PRODUCT_STOCK_KEEPING_UNIT",
              quantity: "YOUR_PRODUCT_QUANTITY",
            },
          ],
        }),
      })
        .then((response) => response.json())
        .then((order) => order.id);
    },
    onApprove(data) {
      return fetch("/my-server/capture-paypal-order", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          orderID: data.orderID,
        }),
      })
        .then((response) => response.json())
        .then((orderData) => {
          // Successful capture! For dev/demo purposes:
          console.log(
            "Capture result",
            orderData,
            JSON.stringify(orderData, null, 2),
          );
          const transaction = orderData.purchase_units[0].payments.captures[0];
          console.log("Transaction Status:", transaction.status);
          console.log("Transaction ID:", transaction.id);
          // When ready to go live, remove the alert and show a success message within this page. For example:
          // const element = document.getElementById('paypal-button-container');
          // element.innerHTML = '<h3>Thank you for your payment!</h3>';
          // Or go to another URL:  window.location.href = 'thank_you.html';
        });
    },
    onCancel(data, actions) {
      console.log(`Order Canceled - ID: ${data.orderID}`);
    },
    onError(err) {
      console.error(err);
    },
  })
  .render("#ideal-btn");

• createOrder

  Implement the createOrder function to allow the JavaScript SDK to submit buyer information and set up the transaction on the click of the button.

  Note: iDEAL requires orders to be created in a currency of EUR.

  Use your server-side Create order call to set up the details of a one-time transaction including the amount, line item detail, and more.

  If order creation fails, the Orders API can return an error in the console.

  After order creation, orders are confirmed with buyer-selected payment source. If the order cannot be processed with the selected payment source, the relevant errors are returned in the console.

• onCancel

  Implement the optional onCancel() function to show a cancellation page or return to the shopping cart.

• onError

  Implement the optional onError() function to handle errors and display generic error message or page to the buyers. This error handler is a catch-all. Errors at this point are not expected to be handled beyond showing a generic error message or page.

5. Capture the transaction

Implement the onApprove function, which is called after the buyer approves the transaction.

Captures the funds from the transaction and shows a message to the buyer to let them know the transaction is successful. The method is called after the buyer approves the transaction on paypal.com.

Because this is a client-side call, PayPal calls the Orders API on your behalf, so you don't need to provide the headers and body.

capture() - Promise returning the order details.

paypal
  .Buttons({
    fundingSource: paypal.FUNDING.IDEAL,
    createOrder() {
      return fetch("/my-server/create-paypal-order", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        // use the "body" param to optionally pass additional order information
        // like product skus and quantities
        body: JSON.stringify({
          cart: [
            {
              sku: "YOUR_PRODUCT_STOCK_KEEPING_UNIT",
              quantity: "YOUR_PRODUCT_QUANTITY",
            },
          ],
        }),
      })
        .then((response) => response.json())
        .then((order) => order.id);
    },
    onApprove(data) {
      return fetch("/my-server/capture-paypal-order", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          orderID: data.orderID,
        }),
      })
        .then((response) => response.json())
        .then((orderData) => {
          // Successful capture! For dev/demo purposes:
          console.log(
            "Capture result",
            orderData,
            JSON.stringify(orderData, null, 2),
          );
          const transaction = orderData.purchase_units[0].payments.captures[0];
          console.log("Transaction Status:", transaction.status);
          console.log("Transaction ID:", transaction.id);
          // When ready to go live, remove the alert and show a success message within this page. For example:
          // const element = document.getElementById('paypal-button-container');
          // element.innerHTML = '<h3>Thank you for your payment!</h3>';
          // Or go to another URL:  window.location.href = 'thank_you.html';
        });
    },
  })
  .render("#ideal-button-container");
//This function displays payment buttons on your web page.

For the capture call details and example responses, see Capture payment for order in the Orders API reference.

If order capture fails, the Orders API can return an error in the console.

6. Handle webhook events

A webhook handler is a script you create on your server that completes specific actions on webhooks that hit your listener URL.

• We recommend subscribing to the CHECKOUT.ORDER.APPROVED webhook event in case a customer accidentally closes the browser and exits the checkout process after approving the transaction through their APM but before finalizing the transaction on your site.
• We also recommend subscribing to the CHECKOUT.ORDER.DECLINED webhook event to receive notifications of any other failure scenarios. This webhook event passes a failure reason code and error message to indicate what caused the error.
• Listen for the CHECKOUT.PAYMENT-APPROVAL.REVERSED webhook as an indication that an approved order wasn't captured within the capture window resulting in a cancellation of the order and a refund the buyer's account. Then notify your buyer of the problem and the reversed order.
• PAYMENT.CAPTURE.PENDING, PAYMENT.CAPTURE.COMPLETED, and PAYMENT.CAPTURE.DENIED webhooks indicate capture status.

See Subscribe to checkout webhooks for more information.

Here are some additional resources as you create webhook handler code:

• Webhook Management API - Manage webhooks, list event notifications, and more.
• Webhook events
  • Checkout webhook events - Checkout buyer approval-related webhooks.
  • Order webhook events - Other order-related webhooks.
• Show order details endpoint - Determine the status of an order.

Sample integration

See a sample iDEAL integration in the PayPal GitHub repository.

Merchant onboarding payment error

Partners need to onboard merchants upfront before they accept payments. iDEAL doesn't support onboarding after making payments, specifically Progressive Onboarding. See the Onboard a merchant section for more details.

When you submit an order with ideal as the payment_source, and the merchant isn't onboarded, you get the following error message:

The 'API caller' and/or 'payee' is not set up to be able to process the selected payment source. If you have already completed the required steps, please allow 2 business days for PayPal to complete the setup. If you continue to receive this error, please contact your Account Manager or check status at https://www.paypal.com/businessmanage/account/payments.