Guides
StatusPlazaCreate Account
  1. Payment methods
  2. 💳 Payment methods
  3. PayPal

Integration

PayPal integration with Buckaroo

PayPal is an online payment method available worldwide. PayPal offers a range of features for both merchants and buyers to ensure secure payments with optional buyer-seller protection.

Buckaroo provides PayPal integration through two models:

  • Processing Model: Buckaroo facilitates the transaction, but does not manage the funds. Merchants must have a PayPal account to accept PayPal payments.
  • Collecting Model: Buckaroo manages the funds on behalf of the merchant, eliminating the need for the merchant to create a PayPal account. Important note: This option is only available for merchants who do not already have a PayPal account or are new to Buckaroo.

Payment Flow

  1. Redirection to PayPal:
    • The consumer is redirected to the PayPal website to log in and confirm the payment.
  2. Return to Merchant:
    • After confirmation, the consumer is redirected back to the return URL provided by the merchant (in the transaction request or by setting a default URL in the Buckaroo Plaza).
  3. Payment Status:
    • The status of the payment can be pending or successful depending on various factors.
    • Note: The PayPal transaction must be completed within 3 hours or it will expire.

Account Settings

For the processing model:

  1. PayPal Business Account:
    • Merchants need a PayPal Business account.
  2. Onboarding:
    • Onboard the PayPal account via the Buckaroo Plaza (Configuration -> PayPal).
    • You will be redirected to the PayPal website, where you need to agree that Buckaroo is allowed to process payments on your behalf.
  3. Email address:
    • Provide your email address used for the PayPal merchant account.

For the collecting model:

Recurrent Billing (currently only available through the processing model)

  • PayPal supports recurrent billing. A billing agreement description can be provided.
  • Merchants must request permission from PayPal to use 'reference transactions'.

Seller Protection

  • To be eligible for seller protection, provide a shipping address by adding the action “ExtraInfo” to the transaction request, which allows you to add the required shipping address to the transaction.
  • You can also define whether or not this address should override the address known to PayPal.

Service Codes and Actions

  • Service Code: paypal
  • Actions: Pay, Refund, PayRecurrent, ExtraInfo, Authorize, Capture, CancelAuthorize

Authorize, Capture and CancelAuthorize are supported on PayPal V2 only.

PayPal Express Checkout

PayPal Express Checkout can be integrated directly on your product page or within your checkout. The setup is identical for both the processing and collecting models and becomes available once onboarding is successfully completed. To implement this, run the script on your page using the PayPalOptions parameter.

PayPal Options Object

  • ContainerSelector (string): Renders the buttons in the defined container selector.
  • buckarooWebsiteKey (string): Your Buckaroo Website key.
  • PayPalMerchantId (string): Your PayPal merchant ID.
  • Currency (string): Transaction currency.
  • Amount (number): Transaction amount.
  • createPaymentHandler (function(data) : Promise): Callback function should return a Promise which should create a PayPal transaction, with service parameter "PayPalOrderId". See dev.buckaroo.nl/PaymentMethods/Description/paypal#pay. Function is invoked with PayPal data object, see PayPal SDK.
  • onShippingChangeHandler (function(data, actions) : Promise) (optional): Callback function used to adjust the shipping amount based on the selected address. See PayPal SDK.
  • OnSuccessCallback (function) (optional): Callback function used to override the default behavior of redirecting the user to the ReturnURL.
  • OnErrorCallback (function(reason)) (optional): Callback function used to override the default behavior of redirecting the user to the ReturnURLReject.
  • OnCancelCallback (function) (optional): Callback function used to override the default behavior of redirecting the user to the ReturnURLCancel.
  • onInitCallback (function) (optional): Callback function which is invoked after the PayPal button has been rendered.
  • onClickCallback (function) (optional): Callback function which is invoked after the PayPal button has been 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
}

Authorize / Capture flow via the SDK

By default, the SDK creates a PayPal order with intent Capture: funds are moved immediately after the buyer approves. To use the Authorize / Capture flow, where funds are reserved at checkout and captured later by the merchant, set the intent option to "Authorize".

Additional option

PropertyTypeRequiredDefaultDescription
intent"Pay" | "Authorize"No"Pay"Selects PayPal's order intent. "Authorize" reserves funds without moving them.

Full example

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

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

let createPaymentHandler = function(data) {
    return fetch("/my-server/start-buckaroo-paypal-authorize", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
            PayPalOrderId: data.orderID,
            Currency: "EUR",
            AmountDebit: 10.00,
            Invoice: "testinvoice 123"
        })
    }).then(function(response) {
        return response.json();
    });
}

let onShippingChangeHandler = function(data, actions) {
    if (data.shipping_address.country_code !== "NL") {
        return actions.reject();
    }
    return actions.resolve();
}

let onSuccessCallback = function() {
    window.location = "/thank-you";
}

let onErrorCallback = function(reason) {
    window.location = "/payment-failed";
}

let onCancelCallback = function() {
    window.location = "/cart";
}

let onInitCallback = function() {
    // Hook here for analytics after the PayPal button has rendered.
}

let onClickCallback = function() {
    // Hook here for analytics after the PayPal button has been clicked.
}

What changes when intent is "Authorize"

When intent is set to "Authorize":

  • The PayPal JS SDK is loaded with the authorize intent.
  • The PayPal order is created with intent AUTHORIZE instead of CAPTURE.
  • After the buyer approves, the createPaymentHandler callback receives a PayPalOrderId.
  • Your server sends an Authorize request to Buckaroo instead of a Pay request.

Server-side Authorize request triggered by createPaymentHandler

{
  "Currency": "EUR",
  "AmountDebit": 10.00,
  "Invoice": "testinvoice 123",
  "Services": {
    "ServiceList": [
      {
        "Name": "paypal",
        "Action": "Authorize",
        "Parameters": [
          {
            "Name": "PayPalOrderId",
            "Value": "3C786053MK04XXXXX"
          }
        ]
      }
    ]
  }
}

Buckaroo returns an Authorize transaction. Funds are reserved on the buyer's PayPal account but are not captured yet. See the PayPal Requests page for the complete Authorize response and push examples.

Capturing or cancelling later

Capturing or cancelling the authorization is done through regular server-to-server Buckaroo gateway requests, not through the SDK.

Use the Authorize transaction key as the OriginalTransactionKey for:

  • Capture
  • CancelAuthorize

See the PayPal Requests page for the full Authorize, Capture and CancelAuthorize request, response and push examples.

The intent option is supported on PayPal V2 only. Omitting this option keeps the existing Pay flow unchanged.


Updated 1 day ago