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 Method | Transaction Flows | Transaction Types |
---|---|---|
PayPal | payment.js | All |
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>
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
Option | Required | Type | Description |
---|---|---|---|
paypal-btn | yes | HTMLElement | Container element into which the button will be rendered. |
currency | yes | string | Currency |
intent | yes | string | Possible values - capture, authorize. Preauthorize flow requires to send authorize. Otherwise, it should be set to capture. |
createOrderEndpoint | yes | string | Your server endpoint where prepareX transaction is implemented |
vaultingWithoutPurchase | no | boolean | Only required with register flow. |
vault | no | boolean | Only required for register and debit/preauthorize with register = true |
userIdToken | no | boolean | Required for One-click payment |
enablePaylater | no | boolean | If you would like to display PayLater button, make sure that this field is set to true |
completeHandler | no | (data) => void | Triggered after successful payment. |
errorHandler | no | (error) => void | Triggered if an error occurred in payment process. |
cancelHandler | no | (data) => void | Triggered if the user canceled the payment process. |
button | no | object | https://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
};
var prepareCall = () => {
// prepare Transaction on your backend
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 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)
Key | Values | Description |
---|---|---|
extraData.shipping_type | "SHIPPING", "PICKUP_IN_STORE", "PICKUP_FROM_PERSON" | Shipping type |
extraData.shipping_cost | string | Shipping 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_name | string | Brand name |
extraData.discount_amount | string | Discount 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"
}
Key | Values | Description |
---|---|---|
referenceUuid | string | Initial transaction UUID |
extraData.useReturnUserExperience | string | Expected value: true |
transactionIndicator | CARDONFILE | Transaction 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:
Key | Values | Description |
---|---|---|
description | string | Item description |
extraData.sku | string | Item SKU |
l2l3Data.taxAmount | string | Item tax amount |