Skip to main content

PayPal Complete Platform

This page provides an overview of the payments methods provided by the PayPal Complete Platform adapter in the IXOPAY platform. It also includes a full list of all configuration options available to you when integrating PayPal Complete Platform within your payments landscape, as well as an overview of the parameters required when submitting a transaction via IXOPAY's API.

Payment Methods​

Payment MethodTransaction FlowsTransaction Types
PayPalpayment.jsDebit, Register, Preauthorize, Capture, Refund, Deregister, Recurring Debit/Preauthorize
PayPal ACDCpayment.jsDebit, Register, Preauthorize, Capture, Refund, Deregister, Recurring Debit/Preauthorize

Integration guide​

PayPal​

PayPal requires you to display the PayPal Button on your Checkout page. This is handled by the payment.js integration.

​1. Embed the payment.min.js in your page

<script data-main="payment-js" src="https://gateway.ixopay.com/js/integrated/payment.1.3.min.js"></script>
note

It is important to set the data-main="payment-js" attribute on the script tag.

​2. Provide a DIV element on your page for the PayPal button

<div id='paypalButtonDiv'></div>

​3. Initialize the payment.js with the following parameters:

  • ID of the DIV element
  • Javascript function to handle payment completion
  • Javascript function to handle error events
  • Javascript function to handle cancellation events
  • PayPal options (see below in example, refer to PayPal Documentation for possible options. The 'vault' option is per default set to 'false' if not otherwise specified. Please refer to the PayPal Documentation for the different button options)
  • Your server endpoint where prepareCall is implemented. It could either be prepare-debit/prepare-preauthorize/prepare-register based on the transaction type

PayPal options​

OptionRequiredTypeDescription
paypal-btnyesHTMLElementContainer element into which the button will be rendered.
currencyyesstringCurrency
intentyesstringPossible values - capture, authorize. Preauthorize flow requires to send authorize. Otherwise, it should be set to capture.
createOrderEndpointyesstringYour server endpoint where prepareX transaction is implemented
vaultingWithoutPurchasenobooleanOnly required with register flow.
vaultnobooleanOnly required for register and debit/preauthorize with register = true
userIdTokennobooleanRequired for One-click payment
enablePaylaternobooleanIf you would like to display PayLater button, make sure that this field is set to true
completeHandlerno(data) => voidTriggered after successful payment.
errorHandlerno(error) => voidTriggered if an error occurred in payment process.
cancelHandlerno(data) => voidTriggered if the user canceled the payment process.
buttonnoobjecthttps://developer.paypal.com/sdk/js/reference/#link-style

<script>
  var paymentJs = new PaymentJs('1.3');

  errorHandler = function (error) {
      // If an error prevents buyer checkout, alert the user that an error has occurred with the buttons using the onError callback
  }

  cancellationHandler = function (data) {
      // When a buyer cancels a payment, they typically return to the parent page.
      // You can instead use the onCancel function to show a cancellation page or return to the shopping cart.
  }

  completeHandler = function (paypalToken) {
      // Captures the funds from the transaction and shows a message that tells the buyer the payment was successful.
      // The method is called after the buyer approves the transaction on the paypal.com website.
      // paypalToken should be passed to the debit request using extraData with the key 'paypalToken'

  }

  var paypalOptions = {
      button: {
          color: gold,
      },
      currency: "EUR",
      intent: "capture" || "authorize", // debit = capture / preauthorize = authorize
      vaultingWithoutPurchase: false // should be set to true if you're doing register call
      vault: false // should be set to true if you would like to vault transaction using PayPal vaulting. for example register / debit + withRegister=true
  };

  // Prepare Transaction
  var prepareCall = () => {
    return fetch('{MY_PREPARE_ENDPOINT}', {
      method: 'POST',
    }).then(function (res) {
      return res.json();
    }).then(function (data) {
      return data.id;
    });
  };

  paymentJs.initPaypal(
    'public-integration-key',
    'paypal-button-div',
    completeHandler,
    errorHandler,
    cancellationHandler,
    paypalOptions,
    prepareCall
  );
</script>

​4. You can now call the Transaction API with the extraData.paypalToken set to the paypalToken returned to the completeHandler.

Prepare Transaction​

PayPal requires to create order/setup token when the PayPal button is being pressed. That's being handled with prepare-debit/prepare-preauthorize/prepare-register API calls. Therefore, you would need to implement prepareDebit call and provide your server endpoint initializing PayPal via PaymentJs.

When using the Hosted Payment Page option, the prepare call can be handled automatically on our side. E.g.

 prepareCall = function() {
    return fetch('', {
        method: 'POST',
        headers: {
            'Accept': 'application/json',
            'Content-Type': 'application/json'
        }
    }).then(function (res) {
        return res.json();
    }).then(function (data) {
        return data.orderID;
    });
}

Additional Prepare Transaction Parameters (CreateOrder)​

KeyValuesDescription
extraData.shipping_type"SHIPPING", "PICKUP_IN_STORE", "PICKUP_FROM_PERSON"Shipping type
extraData.shipping_coststringShipping cost that will be displayed to the customer
extraData.shipping_preference"GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS"By default is being set on the connector level. However, by using this field can be overwritten per transaction. "SET_PROVIDED_ADDRESS" requires to provide shipping details
extraData.brand_namestringBrand name
extraData.discount_amountstringDiscount amount
extraData.experience_context_shipping_preferencestringNO_SHIPPING = no shipping information, e.g. for digital goods

SET_PROVIDED_ADDRESS = show address on PayPal but don't allow the customer to change it - item will be shipped to this address

GET_FROM_FILE = shipping address was not provided, ask the buyer to select a shipping address from their PayPal profile

One-click payment / Customer Initiated Transaction​

To render One-click payment button you would need to do a prepareDebit/preparePreauthorize call to retrieve user-token-id that needs to be passed to paymentJs via paypalOptions.userIdToken.

Example API Request:

{
  "referenceUuid": "referenceUuid",
  "extraData": {
    "useReturnUserExperience": "true"
  },
  "transactionIndicator": "CARDONFILE"
}
KeyValuesDescription
referenceUuidstringInitial transaction UUID
extraData.useReturnUserExperiencestringExpected value: true
transactionIndicatorCARDONFILETransaction Indicator should be CARDONFILE

Example API Response:

{
  "data": {
    "success": true,
    "returnType": "FINISHED",
    "widgetToken": "eyJraWQiOiJhMDRiMjEwZDYzYjU0NWQzODEwOWUxNDM3ZjQ3ZWYxMiIsInR5cCI6IkpXVCIsImFsZyI6IkVTMjU2In0.eyJpc3MiOiJodHRwczovL2FwaS5zYW3kYm94LasdasXBhbC5jb20iLCJzdWIiOiJDRVlINFVNUUpLMzM4IiwiYWNyIjpbImNsaWVudCJdLCJzY29wZSI6WyJCcmFpbnRyZWU6VmF1bHQiXSwib3B0aW9ucyI6eyJjdXN0b21lcl9pZCI6IklpUklSYWR1UEMifSwiYXoiOiJjY2cxOC5zbGMiLCJleHRlcm5hbF9pZCI6WyJQYXlQYWw6Q0VZSDRVTVFKSzMzOCIsIkJyYWludHJlZTozZG04NjdjdHJyZ3Y2Y2R3Il0sImV4cCI6MTcxNTcwNTEwNiwiaWF0IjoxNzE1NzA0MjA2LCJqdGkiOiJVMkFBSVA4NGprc3dfX1pYSHduR21KeVRQV003SkxzbFJLVlI2OHlxOEN4YmhHN1VWNkFWVVlyTTBqbXRyVEZmU3hBbjZKa0hlekNvSUtTdlZ6LUVpR1JxbVl4VWZaRHJOMDY1eXZQRkMySmgtQWkxaXNiV0xOWnh1MWJNa0VkdyJ9._s54YCC8MRqjllX2wDTmo4fQyTkUXl6_7aPOiNwBnVBJfLoQlwIZvtrkvgxU7RPBQy3uiRp-hhK4LGvwRC74CA"
  }
}

Items​

If submitting items, the following fields are Mandatory:

Field
quantity
name
price
extraData.category

Item Additional Parameters:

KeyValuesDescription
descriptionstringItem description
extraData.skustringItem SKU
l2l3Data.taxAmountstringItem tax amount

PayPal ACDC​

​1. Embed the payment.min.js in your page

<script data-main="payment-js" src="https://gateway.ixopay.com/js/integrated/payment.1.3.min.js"></script>
note

It is important to set the data-main="payment-js" attribute on the script tag.

​2. Provide an input field for the paypalToken which will be created later.

<input type="hidden" name="paypalToken" id="paypalToken" value="">

​3. Initialize the payment.js with the following parameters:

paymentJsPayPal.initPaypal(
  'the public integration key of your connector',
  {
    cardName: 'card-name-field-container',
    cardNumber: 'card-number-field-container',
    cardCvv: 'card-cvv-field-container',
    cardExpiry: 'card-expiry-field-container'
  },
  completeHandler,     <!-- your callback function for when the token has been created -->
  errorHandler,        <!-- your callback function in case of error -->
  cancellationHandler, <!-- your callback funciton in case of cancellation -->
  payPalOptions,       <!-- see PayPalOptions -->
  prepareCall          <!-- see prepareCall -->
);

completeHandler

The completeHandler callback will be called once the PayPal token has been created

Example

completeHandler = function (payPalToken) {
    // do things when the PayPal token is created
    console.log('done: ' + payPalToken);

    // set the PayPal token and submit
    <!-- important to name it paypalToken -->
    document.getElementById("paypalToken").value = paypalToken;
    document.getElementById("payment-form").submit();
}

prepareCall

The prepareCall must be implemented by you and is based on the transaction type: prepare-debit/prepare-preauthorize/prepare-register

Please refer to Prepare Transaction

When using the Hosted Payment Page option, the prepare call can be handled automatically on our side. E.g.

  prepareCall = function() {
      document.getElementById('loader').style.display = '';

      return fetch('{{ paypal.prepareCallEndpoint }}', {
          method: 'POST',
      }).then(function (res) {
          return res.json();
      }).then(function (data) {
          return data.orderID;
      });
  }

errorHandler, cancellationHandler

Here you may implement handling of scenarios for errors and user cancellations.

payPalOptions

OptionRequiredTypeDescription
currencyyesstringCurrency
intentyesstringPossible values - capture, authorize. Preauthorize flow requires to send authorize. Otherwise, it should be set to capture.
vaultingWithoutPurchasenobooleanShould be set to true if you would like to vault transaction using PayPal vaulting. for example register / debit + withRegister=true
vaultnobooleanShould be set to true if you would like to vault transaction using PayPal vaulting. for example register / debit + withRegister=true
stylenoobjectHere you may override the style of the card fields

Example

var paypalOptions = {
      currency: "EUR",
      intent: "authorize",
      vaultingWithoutPurchase: false,
      vault: false,
      style: {
          'input': {
              'font-size': '12px',
              'line-height': '1.7rem',
              'color': '#000',
              'padding': '5px',
              'appearance': 'none'
          },
          ':focus': {
              'padding': '5px',
              'outline': 'none'
          }
     }
};

​4. Trigger Payment with billing address data

Billing address data should be collected and submitted with the card data.

To trigger the payment you may use the paymentjs.trigger(data) function.

Example

document.getElementById('submit-btn').addEventListener('click', function (event) {
  event.preventDefault();
  paymentJs.trigger({
    billingAddress: {
      addressLine1: document.getElementById('card-billing-address-line-1').value,
      addressLine2: document.getElementById('card-billing-address-line-2').value,
      adminArea1: document.getElementById('card-billing-address-admin-area-line-1').value,
      adminArea2: document.getElementById('card-billing-address-admin-area-line-2').value,
      countryCode: document.getElementById('card-billing-address-country-code').value,
      postalCode: document.getElementById('card-billing-address-postal-code').value
    }
  });
});

Please note that billing address line 1 and country code are mandatory.

Last updated on