WL SIPS DOCS

Release 22.5

go directly to content

Search by keywords

PayPal integration

To search in the page use Ctrl+F on your keyboard

WL Sips is a secure multi-channel e-commerce payment solution that complies with the PCI DSS standard. It allows you to accept and manage payment transactions by taking into account business rules related to your activity (payment upon shipping, deferred payment, recurring payment, payment in instalments, etc.).

The purpose of this document is to explain the PayPal means of payment integration into WL Sips.

This document is intended to help you implement the PayPal means of payment on your e-commerce site.

It includes:

  • functional information for you
  • implementation instructions for your technical team

To get an overview of the WL Sips solution, we advise you to consult the following documents:

  • Functional presentation
  • Functionality set-up guide

PayPal is an online mean of payment used in more than 200 countries.

To pay with PayPal, the customer must have a PayPal account with registered means of payment. During the payment, after selecting PayPal, the customer must identify himself and choose one of the means of payment registered on their account. If the customer does not have a PayPal account, he can create one during the payment process.

Payment channels
Internet V Default payment channel
MOTO X
Fax X
IVR X
Means of payment
Immediate payment V
Payment at the end of the day V
Deferred payment V 29 days maximum
Payment upon shipping V
Payment in instalments X
Subscription payments X
OneClick payment V
Currency management
Multicurrency acceptance V
Currency settlement V

The maximum authorisation period for a PayPal transaction is 29 days. After this period, the transaction is expired.

The payment review is a PayPal functionality. This functionality identifies risky transactions and informs you to put deliveries on hold until PayPal has assessed the risk of the transaction.

If a payment is being reviewed by PayPal, the status of the transaction can be one of the followings:

  • TO_CONFIRM_AUTHOR (payment verification at authorisation stage)
  • TO_CONFIRM_CAPTURE (payment verification at remittance stage)

A batch processing is carried out daily to update these transactions to final statuses:

  • REFUSED (if the payment has been refused)
  • TO_CAPTURE/TO_VALIDATE (if the payment has been refused)
  • CAPTURED (if the remittance has been made)

The diagram of the Making a PayPal payment paragraph illustrates these statuses as well as the transitions.

The final status will appear in your transaction report to allow you to continue processing the order.

Attention: the cash management operations are not available for transactions with the TO_CONFIRM_AUTHOR or TO_CONFIRM_CAPTURE status.

WL Sips allows you to send the shopping cart information to PayPal.

PayPal validates the amounts by applying the following rules:

  • Amount=ShoppingCart.TotalAmount+ShoppingCart.TotalTaxAmount+Delivery.ChargeAmount
  • ShoppingCartDetail.TotalAmount = ∑items item.UnitAmount∗item.Quantity
  • ShoppingCartDetail.TotalTaxAmount = ∑items item.UnitTaxAmount∗item.Quantity

If the validation of one of the three rules fails, the payment is cancelled by PayPal. The WL Sips response code and the acquirer response code will have the value "12" (Invalid Request).  

PayPal displays the delivery address on their payment pages. The delivery address can be retrieved from two different sources:

  • from the customer's PayPal account
  • from the payment requests you send to WL Sips

The selection is made through the paymentMeanData.paypal.addrOverride field:

  • The value NO_OVERRIDE selects the delivery address specified in the customer's PayPal account.
  • The value OVERRIDE selects the delivery address specified in the payment request. If no address is provided in the request, the account address is displayed (default value).
  • The value NO_DISPLAY does not display the delivery address.
IMPORTANT: if the delivery address is overridden and it does not conform to the validations made by PayPal, an error is returned. In this case, to avoid the payment being blocked and an error page being displayed, WL Sips deactivates the overriding of the delivery address (the address used will then be the one linked to the customer's PayPal account).

You must have a PayPal account in order to use the PayPal mean of payment on your website. It must be a Business account (the type of account is chosen when you register at http://www.paypal.com).

If you have several active shops, we suggest you create a PayPal account for each one.

On your PayPal account, you as a merchant have to authorise the payment service provider (PSP) to call PayPal API.

Attention: the screenshots of the PayPal pages are provided here for information only. PayPal may edit their pages.

In your PayPal Business account, go to Account Settings, then API access:


PayPal page screenshot: click on update next to API access

Click on the Grant API permission link.



The Add new third-party grant window opens. In the text field, enter the WL Sips technical account sips-gestion-services_api1.worldline.com and click on Search.

Select the following options:

  • Use Express Checkout to process payments
  • Issue a refund for a specific transaction
  • Process your shopper's credit or debit card payments
  • Authorize and capture your PayPal transactions
  • Obtain information about a single transaction
  • Obtain authorization for pre-approved payments and initiate pre-approved transactions
  • Use Express Checkout to process mobile payments

After that, click on the Add button.



Attention:

If you want to duplicate transactions, you must also select the option "Charge an existing customer based on a prior transaction".

Once your PayPal account is created, you can contact the technical support to ask them to link this account to your WL Sips shop. The only information needed is the email address you used to create your PayPal account.

WL Sips gives you the option to accept OneClick payments with PayPal. For this, you must:

  • Have obtained permission from PayPal to duplicate the transactions.
  • Have subscribed to WL Sips OneClick PayPal (contact the technical support).

You will then have to send a unique wallet identifier per customer (merchantWalletId field) within your payment requests.

To include PayPal transactions into chargeback reports (optional) generated by WL Sips, select the following option:


screenshot showing option to check: generate consolidated reports for all accounts

Tip: chargeback reports generation is not activated by default on WL Sips. Contact the technical support to activate it if necessary.

WL Sips offers you two solutions to integrate the PayPal mean of payment:

  • Sips Paypage which directly acts as the payment interface with clients via their web browser.
  • Sips Office which gives you the opportunity to display your payment pages and works through a server-to-server dialog.

The remittance modes available for a PayPal transaction are:

  • Cancellation mode: default mode allowing transaction remittance on a predefined date, called capture delay. When this capture delay is reached, the remittance is sent automatically. This delay is set via the captureDay field with its 0 default value (end-of-day payment).
  • Validation mode: you must validate the transaction to trigger the remittance. A capture delay must also be defined. When this capture delay is reached or exceeded, you will not be able to validate the transaction, which will therefore expire automatically.
  • Immediate mode: the authorisation and remittance are executed online simultaneously.

The diagram below explains the different transaction statuses according to the chosen capture mode:


diagram showing the different statuses a transaction goes through

image too complex to describe, please contact the support

The payment process for Sips Paypage is described below:


diagram representing the kinematics of a Paypal payment with the Sips Paypage connector

1) After finalizing the order on the merchant website, the customer proceeds to the payment. 2) The customer is redirected to the payment pages hosted on the WL Sips side and selects Paypal. 3) The customer is redirected to the Paypal login and payment pages. 4) When the customer returns to WL Sips the ticket with the result is displayed. 5) If the customer clicks on the return to shop button, his redirected to the merchant's website which unlocks the manual response. 6) The WL Sips engine also sends an automatic response to the merchant website.

The following fields have a particular behaviour:

Field name Remarks/rules
captureDay The value sent in the request must be 29 at a maximum.
paymentMeanData.PayPal.invoiceId PayPal order number. A uniqueness check is made by PayPal.
paymentMeanData.PayPal.addrOverride Allows you to override the address of the customer registered by PayPal or to hide this address on the PayPal pages.
paymentMeanData.PayPal.landingPage Allows to not display PayPal registration form when the customer is redirected to the PayPal site.
paymentMeanData.PayPal.mobile Indicates whether the terminal used is a mobile device (allows to redirect the customer directly to the PayPal mobile site).
paymentMeanData.PayPal.orderDescription Description of the purchased products.
paymentMeanData.PayPal.dupFlag Makes it possible to duplicate the transaction. The default value is "false" (cannot be duplicated).
paymentMeanData.PayPal.dupDesc Makes it possible to indicate the reason for potential duplication when the value of paymentMeanData.paypal.dupFlag is "true". The transaction details will be displayed on your PayPal account.
paymentMeanData.PayPal.dupCustom Free field at your disposal. This field is taken into account when the value of paymentMeanData.paypal.dupFlag is "true".
paymentMeanData.PayPal.dupType Defines the type of duplication. The default value is "InstantOnly". This value is taken into account when the value of paymentMeanData.paypal.dupFlag is "true".

The following table summarises the different response cases to be processed:

Status Response fields Action to take
Payment accepted acquirerResponseCode = 00
authorisationId = (cf. the Data Dictionary).
You can deliver the order.
Acquirer refusal acquirerResponseCode = (cf. the Data Dictionary). The authorisation is refused for a reason unrelated to fraud.
If you have not opted for the "new payment attempt" option (please read the Functionality set-up Guide for more details), you can suggest that your customer pay with another means of payment by generating a new request.
Outstanding payments acquirerResponseCode = 60 You must wait until the transaction automatic update to know its final status and whether you can deliver the order. For these transactions, it is necessary to use transactions reports to decide whether to continue processing the order.
Refusal due to the number of attempts reached responseCode = 75 The customer has made several attempts that have all failed.
Refusal due to a technical issue acquirerResponseCode = 90-98
responseCode = 90, 99
Temporary technical issue when processing the transaction. Suggest that your customer redo a payment later.

For the complete response codes (responseCode) and acquirer response codes (acquirerResponseCode), please refer to the Data dictionary.

In the event of a refusal, PayPal determines whether the customer can use another mean of payment registered on their account. If so, PayPal sends specific information that allows WL Sips to redirect the customer back to PayPal for a new attempt.

This functionality allows you to increase your conversion rate for a refused payment as it prevents the customer from returning to your website and relaunching the entire payment process.

You have the option to accept OneClick payments with PayPal on Sips Paypage. You must have subscribed to the WL Sips OneClick PayPal service and ask PayPal to allow you to duplicate transactions (cf. the paragraph Activating OneClick payment).

You must then send the merchantWalletId field associated with your customer in each payment request.

The following page is then displayed when enrolling a PayPal account in the WL Sips wallet:


screenshot of hte OneClick page

If a PayPal account has already been added to the WL Sips wallet, the following selection page will be displayed and the payment can be validated with a single click:


screenshot displaying the existing Paypal wallet

The payment process for Sips Office is described below:


diagram representing the kinematics of a Paypal payment with the Sips Office connector

1) The customer finalizes and pays for his order directly on the merchant website. 2) The merchant initializes the payment with WL Sips (PaymentProviderInitialize). 3) The merchant redirects the customer to the Paypal identification and payment pages (redirectionUrl). 4) The customer is then redirected to the merchant website (merchantReturnUrl). 5) The merchant finalizes the payment with WL Sips (PaymentProviderFinalize). 6) The merchant displays the result of the payment to the customer via his website.

The initialisation of a PayPal payment is made by calling the paymentProviderInitialize method.

The following generic fields are populated in the case of a PayPal payment initialisation:

Field name Remarks/rules
captureDay The value sent in the request must be 29 at a maximum.
paymentMeanBrand Must be populated with PAYPAL.
merchantReturnUrl Merchant return URL

You must populate the following specific fields in the initialisation request for a PayPal payment:

Field name Remarks/rules
paymentMeanData.PayPal.invoiceId PayPal order number. A uniqueness check is made by PayPal.
paymentMeanData.PayPal.addrOverride Allows you to override the address of the customer registered by PayPal or to hide this address on the PayPal pages.
paymentMeanData.PayPal.landingPage Allows to not display PayPal registration form when the customer is redirected to the PayPal site.
paymentMeanData.PayPal.mobile Indicates whether the terminal used is a mobile device (allows to redirect the customer directly to the PayPal mobile site).
paymentMeanData.PayPal.dupFlag Makes it possible to duplicate the transaction. The default value is "false" (cannot be duplicated).
paymentMeanData.PayPal.dupDesc Makes it possible to indicate the reason for potential duplication when the value of paymentMeanData.paypal.dupFlag is "true". The transaction details will be displayed on your PayPal account.
paymentMeanData.PayPal.dupCustom Free field at your disposal. This field is taken into account when the value of paymentMeanData.paypal.dupFlag is "true".
paymentMeanData.PayPal.dupType Defines the type of duplication. The default value is "InstantOnly". This value is taken into account when the value of paymentMeanData.paypal.dupFlag is "true".

The following table summarises the different response cases to be processed:

Status Response fields Action to take
Payment initialisation accepted acquirerResponseCode = 00
authorisationId = (cf. the Data Dictionary).
messageVersion = message version retrieved in response to the payment initialisation.
redirectionData = redirection data retrieved in response to the payment initialisation.
redirectionUrl = redirection URL to the PayPal website.
Redirect the customer to redirectionUrl.
Payment initialisation rejected
responseCode = <> 00
See the field errorFieldName, then fix the request.
If the problem persists, contact the technical support.
Acquirer refusal acquirerResponseCode = (cf. the Data Dictionary). The authorisation is refused for a reason unrelated to fraud, you can suggest that your customer pay with another means of payment by generating a new request.
Refusal due to a technical issue acquirerResponseCode = 90-98
responseCode = 90, 99
Temporary technical issue when processing the transaction. Suggest that your customer redo a payment later.

For the complete response codes (responseCode) and acquirer response codes (acquirerResponseCode), please refer to the Data dictionary.

The customer must be redirected to the redirectionUrl URL provided in response of the paymentProviderInitialize method. This redirection consists of making a POST call on the redirectionUrl URL obtained in the response to the payment initialisation. The POST settings to be transmitted are redirectionData and messageVersion, also obtained in the response to the payment initialisation.

At the end of the payment process, the customer is redirected to the URL provided in the initialisation request merchantReturnUrl. The following fields are sent in POST and must be retrieved to finalise the payment:

Field name Remarks/Rules
responseCode Redirection process response code
redirectionData Redirection data retrieved in response to the payment initialisation.
messageVersion Message version retrieved in response to the payment initialisation.
amount Transaction amount in cents
merchantId Shop identifier
transactionReference Transaction reference
transactionId Transaction identifier
transactionDate Transaction date

This last step allows you to obtain the payment status. The settings obtained during the redirection after the payment process on the PayPal website are to be transmitted during this call. The method used to finalise a payment is paymentProviderFinalize.

Tip: you can obtain a code 24 "Operation impossible" in response to your paymentProviderFinalize request. This code means that this request has already been sent and processed for the transaction in question. If you are unable to identify this processing, please use the GetTransactionData function of the diagnostic service: this operation allows you to retrieve information relating to a transaction previously created using the WL Sips.

You have to populate the following specific fields in the finalisation request for a PayPal payment.

Field name Remarks/Rules
redirectionData Redirection data retrieved after the customer returns to your website (cf. Redirecting the customer to the PayPal website).
messageVersion Message version retrieved after the customer returns to your website (cf. Redirecting the customer to the PayPal website).

The following table summarises the different response cases to be processed:

Status Response fields Action to take
Payment accepted acquirerResponseCode = 00
authorisationId = (cf. the Data Dictionary).
transactionStatus = (cf. the Data Dictionary).
You can deliver the order.
Acquirer refusal acquirerResponseCode = (cf. the Data Dictionary). The authorisation is refused for a reason unrelated to fraud, you can suggest that your customer pay with another means of payment by generating a new request.
Refusal due to a technical issue acquirerResponseCode = 90-98
responseCode = 90, 99
Temporary technical issue when processing the transaction. Suggest that your customer redo a payment later.

For the complete response codes (responseCode) and acquirer response codes (acquirerResponseCode), please refer to the Data dictionary.

The paymentProviderGetContext method is optional and allows you to retrieve information about the customer and the current payment. The request is submitted to PayPal directly and allows you to obtain information about the delivery address, the customer email and the status of payment at PayPal.

This method must be called after the customer redirection from the PayPal page to your website and before the finalisation of a payment. If this method is called after the finalisation, PayPal may refuse to provide the information.

Below is a list of fields that must be populated for this method:

Field name Remarks/rules
redirectionData Redirection data.
messageVersion Message version.
Field name Remarks/rules
paymentMeanData.PayPal.token PayPal token allowing the payment to be carried out.
paymentMeanData.PayPal.payerId Customer unique ID (PayPal data).
paymentMeanData.PayPal.payerStatus

Customer status (PayPal data).

  • verified
  • unverified
paymentMeanData.PayPal.payerBusiness Customer brand name.
paymentMeanData.PayPal.paymentStatus
Payment status (PayPal data).
  • PaymentActionNotInitiated
  • PaymentActionFailed
  • PaymentActionInProgress
  • PaymentActionCompleted
paymentMeanData.PayPal.payerSuffix Customer suffix
paymentMeanData.PayPal.deliveryAddressStatus
  • none
  • Confirmed
  • Unconfirmed
IMPORTANT: it is compulsory for any cash management operation concerning a PayPal transaction to be processed only by WL Sips tools. Initiating cash management from your PayPal account will cause inconsistencies between WL Sips and PayPal transaction statuses.

The following operations are available on PayPal transactions:

Cash management
Cancellation V
Validation V
Refund V
PayPal refund requests are processed immediately.
Refunds can be made up to 60 days after purchase. Any refund requests made after this deadline will result in the WL Sips response code "12" despatch.
Duplication V See the paragraph Duplicating a PayPal transaction.
Credit X

The diagram below informs you which cash management operation is available when a transaction is in a given state:


diagram showing available operations depending on the status of the transaction

image too complex to be described, please contact the support

The process of duplicating a transaction requires the initial transaction to be eligible for duplication. Four fields must be transmitted in the initial payment request:

  • paymentMeanData.PayPal.dupFlag
  • paymentMeanData.PayPal.dupDesc
  • paymentMeanData.PayPal.dupType
  • paymentMeanData.PayPal.dupCustom
Attention: PayPal must have authorised your account to duplicate transactions. Contact PayPal if you require this functionality.

To mark the transaction as eligible for duplication, you must specify it as such in the creation message sent to WL Sips by populating the thepaymentMeanData.paypal.dupFlag field with the "true" value.

The dupDesc field is optional and used only if the dupFlag field value is "true".

This field is used to add a description to the duplication process. The description will be displayed on the PayPal payment details page.

Note: the field length is limited to 127 characters (ANS).

The dupType field is optional and used only if the dupFlag field value is "true".

The accepted values are:

  • ANY: you accept any payment method for the billing agreement, even though the movement of funds to your account may take a few days. This includes checks, in addition to credit and debit cards, and the PayPal balance.
  • INSTANTONLY: the means of payment you accept are limited to credit and debit cards and the PayPal balance (you force an immediate payment).
Note: by default, the value of this field is INSTANTONLY.

The dupCustom field is optional and used only if the dupFlag field value is "true".

This field is a custom annotation field reserved for you. It is displayed in the details of your transactions in your PayPal back-office.

The reports provided by WL Sips allow you to have a comprehensive and consolidated view of your transactions, cash operations, accounts and chargebacks. You can use this information to improve your information system.

The availability of the PayPal transactions for each type of report is summarised in the table below:

Reports availability
Transactions report V
Operations report V
Reconciliations report V
Chargebacks report V
Attention: for PayPal transactions, the paymentMeanBrand field is populated with the value PAYPAL.
To include PayPal transactions in chargeback reports, you have to activate the option on your PayPal account.

You can view your PayPal transactions and perform various cash management operations with Sips Office Extranet.

Here are the details of a PayPal transaction. Some specific information is displayed such as PayPal authorisation number:



This site uses trackers to improve your experience, perform analysis and researches on your use of WL Sips documentation website.
You have several options:
Closing this banner you refuse the use of trackers on your device.

Configuration