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.jsAll

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
};

paymentJs.initPaypal(
'public-integration-key',
'paypal-button-div',
completeHandler,
errorHandler,
cancellationHandler,
paypalOptions,
prepareCallEndpoint
);
</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 prepareDebit/preparePreauthorize/prepareRegister API calls. Therefore, you would need to implement prepareDebit call and provide your server endpoint initializing PayPal via PaymentJs.

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

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