Integration

PayPal is an online payment method available worldwide. PayPal offers a range of features for both merchant and buyer to make sure any payment is processed secure and with a number of optional buyer-seller protection options. Both buyer and merchant accounts can be assigned as verified by linking them to a credit card or bank account.

Buckaroo offers PayPal in a processing model. Processing means that Buckaroo will not handle the actual money. A merchant is required to create a PayPal account and will receive payments made with other PayPal accounts on his own PayPal account.

Payment flow

When the payment request is done, the consumer is redirected to the PayPal website where he will be asked to log in to his account (or create a new account). After he has logged in he will be asked to agree to the payment or, when starting a recurrent payment, to accept the billing agreement. After he accepts, he will be redirected back to the return url provided by the merchant, either in the transaction request or by setting a default redirect url in the Buckaroo Payment Plaza under website settings. The status of the payment can be either pending or successful, depending on a number of reasons (PayPal account status, PayPal fraud management filters, etc.).

A PayPal payment has a lifetime of 3 hours; this means that as soon as the consumer is redirected to PayPal, the payment must be completed within 3 hours or it will expire. In the event that the consumer irregularly ends the payment process (e.g. by closing the browser window before returning to the web shop), the payment status will be retrieved from PayPal at a regular interval and when it changes, the merchant web shop is updated via the transaction push. It is therefore recommended to enable the push response in the Payment Plaza when implementing PayPal.

PayPal account settings

To be able to use PayPal payments through the Buckaroo Gateway, it is necessary to have a PayPal Business account. You can either create a new account or use an existing account if you already have one you wish to use for this purpose.

After creating a PayPal account, you have to onboard your PayPal account before you are able to process transactions. This can easily be done via the Buckaroo Plaza. Under "Configuration" - "PayPal" you can onboard your PayPal account. Here you are redirected to PayPal, where you need to agree that Buckaroo is allowed to process transactions on your behalf. It is possible to use different PayPal accounts per unique website. For more information see this article.

Buckaroo subscription settings

To be able to process PayPal payments on your behalf, you must provide Buckaroo with the e-mail address you use for your PayPal merchant account. All payments and refunds performed will be added to, or subtracted from, this PayPal account’s balance.

Recurrent Billing

PayPal supports recurrent billing. This means it is possible to ask a consumer to accept a billing agreement the first time he performs a payment through PayPal for a certain service or subscription a merchant offers. The first payment will be done after the consumer accepts the agreement. Any following payment for the same subscription or service can be done through recurrent billing. The payment request for the recurrent payments can be sent to Buckaroo without the need for interaction with the consumer, making it ideal for regular subscription payments. The amount and description for the recurrent payments can be different from the initial amount, so when variable amounts are required (e.g. for billing of telephone calls or other variable usage) this is no problem.

When using recurrent billing (known at PayPal as reference transactions) it is possible to pass an optional billing agreement description. This description will be used as the description the consumer sees in his PayPal account in his listing of billing agreements. In this list he can see all agreements he has accepted and he can stop the agreement. Make sure the description is an accurate depiction of the subscription or service (e.g. ‘2 Year subscription for 24 issues of Magazine X’). If the consumer agrees, the first payment is automatically charged from his account. If he doesn’t accept the agreement, no charge will be done. If the consumer cancels the agreement (which he can at any time) any subsequent recurrent transaction will be rejected by PayPal.

To be able to use recurrent billing, a merchant must request this feature to be enabled for his PayPal account by sending a request to PayPal asking for permission to use ‘reference transactions’. PayPal will decide if a merchant is allowed to perform reference transactions. Contact PayPal for details: To enable reference transactions for the Sandbox testing environment, go to https://www.paypal.com/mts and make a request through “Contact Technical Support”. Remember to include your test account email address (email_123456_biz@domain.nl) in the request. To have Reference Transactions Enabled for your live account you need to contact your Account Manager or PayPal Merchant Services. Go to the "Contact Us" link once you login to your PayPal Account.

Seller Protection

To be eligible for seller protection by PayPal one of the requirements is that a shipping address is provided by the merchant or selected by the consumer. The action ExtraInfo can be added to the transactionrequest as a supplementary action which allows you to add the required shipping address to the transaction. Together with this data you can also define that you want the address you supply to override the consumers address as on file at PayPal and whether or not to display the shipping address in the Paypal pages. If no override is demanded, the address the consumer chooses will be returned as output parameters, along with whether or not the address is confirmed by PayPal and whether or not you are eligible for any kind of protection and which type of protection.

For more info go to: https://www.paypal.com/nl/webapps/mpp/seller-protection (Dutch) https://www.paypal.com/uk/webapps/mpp/seller-protection (English, United Kingdom)

Servicecode and actions

For PayPal, use the service code paypal.

The service supports the following actions: Pay, Refund, Payrecurrent, Extrainfo. All can be used with channel 'Web'.

PayPal Express Checkout

It is possible to run the PayPal Express Checkout on your own product page or shopping basket. This is only possible if you are onboarded via the Plaza via https://plaza.buckaroo.nl/Configuration/PayPal, and on one-off transactions.

To do this, run below script on your page with the PayPalOptions parameter.

The PayPalOptions object:

• ContainerSelector string - Renders the buttons in the defined container selector.

• buckarooWebsiteKey string - Your Buckaroo Websitekey.

• 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 https://developer.paypal.com/sdk/js/reference/#link-dataattributes.

• (optional) onShippingChangeHandler function(data, actions) : Promise - Callback function used to adjust the shipping amount based on the selected address. See https://developer.paypal.com/sdk/js/reference/#link-onshippingchange

• (optional) OnSuccessCallback function - Callback function used to override the default behavior of redirecting the user to the ReturnURL.

• (optional) OnErrorCallback function(reason) - Callback function used to override the default behavior of redirecting the user to the ReturnURLReject.

• (optional) OnCancelCallback function - Callback function used to override the default behavior of redirecting the user to the ReturnURLCancel.

• (optional) onInitCallback function - Callback function which is invoked after the PayPal button has been rendered

• (optional) onClickCallback function - 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
}