Client SDK

The Client SDK can be used with Payconiq, PayPal, Bancontact, and iDeal.

Initiating Client-Side Payments

After initiating a server-side Pay request, you can handle the payment on the client side. To do this, you need to initialize the Client SDK with the following parameters (three for iDeal):

• Container Selector (string): Use a query selector format to select a DOM element.
• Transaction Key (string): Use the transaction key from the server-side Pay response, found in the “Key” field of the JSON response.
• Processing (boolean) [iDeal only]: Set to true if your iDeal subscription is processing, otherwise set to false.

When initiated, the Client SDK will render a minimal widget inside the specified container element. This widget will display a QR code and listen for status updates. If the consumer is using a mobile device, the script will redirect them directly to the corresponding app (Payconiq, Bancontact, etc.) to complete the payment.

After the payment is completed, cancelled, or failed, the consumer will be redirected to the ReturnUrl by the SDK.

Including the Client SDK

Include the ClientSDK like this in the bottom of the BODY element of your page. Like this:

<script src="https://checkout.buckaroo.nl/api/buckaroosdk/script"></script>

Bancontact Widget Language Options

The Bancontact widget supports multiple languages (English, French, and Dutch). To set the correct language, include the language code in the script URL ("en" for English, "fr" for French, and "nl" for Dutch):

<script src="https://checkout.buckaroo.nl/api/buckaroosdk/script/en"></script>

📘

Notes

• The default language is Dutch.
• The only dependency of the Buckaroo Client SDK is jQuery 1.9+

Examples

Payconiq script example

$(document).ready(
    function() {
        BuckarooSdk.Payconiq.initiate("#payconiqQr", "94EDDFBCFF774714AEDE0F9346XXXX");
    });

Bancontact script example

$(document).ready(
    function() {
        BuckarooSdk.BancontactMobile.initiate("#bancontactMobileButton", "94EDDFBCFF774714AEDE0F9346XXXX");
    });

iDEAL script example

$(document).ready(
    function() {
        BuckarooSdk.IdealQr.initiate("#idealQrButton", "94EDDFBCFF774714AEDE0F9346XXXX", false);
    });

PayPal Express Checkout

You can run the PayPal Express Checkout on your own product page or shopping basket if you are onboarded via the Plaza and only for one-off transactions. Use the script below with the PayPalOptions parameter.

PayPal Options Object

• containerSelector (string): Defines where the buttons will be rendered.
• buckarooWebsiteKey (string): Your Buckaroo Website key.
• paypalMerchantId (string): Your PayPal merchant ID.
• currency (string): Transaction currency.
• amount (number): Transaction amount.
• createPaymentHandler (function(data): Promise): A callback function that creates a PayPal transaction. It should return a Promise and include the PayPal Order ID.

Optional parameters:

• (Optional) onShippingChangeHandler (function(data, actions): Promise): Adjusts the shipping amount based on the selected address.
• (Optional) onSuccessCallback (function): Overrides the default success behavior.
• (Optional) onErrorCallback (function(reason)): Overrides the default error behavior.
• (Optional) onCancelCallback (function): Overrides the default cancel behavior.
• (Optional) onInitCallback (function): Invoked after the PayPal button is rendered.
• (Optional) onClickCallback (function): Invoked after the PayPal button is clicked.

$(document).ready(function() {
    let PayPalOptions = {
      containerSelector: "#paypal-container",
      buckarooWebsiteKey: "{{your_websitekey}}",
      paypalMerchantId: "{{your_PayPalMerchantId}}",
      currency: "EUR",
      amount: 0.01,
      createPaymentHandler: createPaymentHandler,
      onShippingChangeHandler: onShippingChangeHandler,
      onSuccessCallback: onSuccessCallback,
      onErrorCallback: onErrorCallback,
      onCancelCallback: onCancelCallback,
      onInitCallback: onInitCallback,
      onClickCallback: onClickCallback,
    };

    BuckarooSdk.PayPal.initiate(PayPalOptions);
});

let createPaymentHandler = function(data) {
    // Call to create PayPal Order including PayPal Order ID (dev.buckaroo.nl/PaymentMethods/Description/paypal#pay)
}

let onShippingChangeHandler = function(data, actions) {
    // EXAMPLE - Reject non-US addresses
    if (data.shipping_address.country_code !== 'US') {
      return actions.reject();
    }

    // Patch the shipping amount
    const shippingAmount = data.shipping_address.state === 'CA' ? '0.00' : '5.00';
    return actions.order.patch([
      {
        op: 'replace',
        path: '/purchase_units/@reference_id==\'default\'/amount',
        value: {
          currency_code: 'USD',
          value: (parseFloat(baseOrderAmount) + parseFloat(shippingAmount)).toFixed(2),
          breakdown: {
            item_total: {
              currency_code: 'USD',
              value: baseOrderAmount
            },
            shipping: {
              currency_code: 'USD',
              value: shippingAmount
            }
          }
        }
      }
    ]);
}

let onSuccessCallback = function() {
    // custom success behavior
}

let onErrorCallback = function(reason) {
    // custom error behavior
}

let onCancelCallback = function() {
    // custom cancel behavior
}

let onInitCallback = function() {
    // additional behavior after initiation
}

let onClickCallback = function() {
    // additional behavior after click
}