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:

• Send an email to [email protected] to request PayPal collecting.

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 (can all be used with channel 'Web')
• When using the collecting payment method, merchants should select PayPal Payfac as the acquirer in the subscription details view.

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
}