Introduction
Sherlock's 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 Sherlock's.
Who does this document target?
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 Sherlock's solution, we advise you to consult the following documents:
- Functional presentation
- Functionality set-up guide
Understanding PayPal payments with Sherlock's
General principles
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.
Acceptance rules
Available functionalities
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 |
Authorisation request
The maximum authorisation period for a PayPal transaction is 29 days. After this period, the transaction is expired. Please note that if the capture delay exceeds 6 days, the funds are not on hold and the transaction may be refused. In the event of refusal, we invite you to examine the response code sent by PayPal.
Payment review
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.
Shopping cart details
Sherlock's 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 Sherlock's response code and the acquirer response code will have the value "12" (Invalid Request).
Delivery address management
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 Sherlock's
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.
Creating your 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.
Setting your PayPal account
On your PayPal account, you as a merchant have to authorise the payment service provider (PSP) to call PayPal API.
In your PayPal Business account, go to Account Settings, then API access:
![PayPal page screenshot: click on update next to API access](../../resources/images/en/paypal-integration/Configuring-PayPal-account-1.png)
Click on the Pre-built payment solution link.
The Add new third-party grant window opens. In the text field, enter the Sherlock's 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 customers credit or debit card payments
- Authorize and capture your PayPal transactions
- Obtain information about a single transaction
- Search your transactions for items that match specific criteria and display the results
- 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.
If you want to duplicate transactions, you must also select the option "Charge an existing customer based on a prior transaction".
Adding PayPal account to Sherlock's
Once your PayPal account is created, you can contact the technical support to ask them to link this account to your Sherlock's shop. The only information needed is the email address you used to create your PayPal account.
Including PayPal transactions into chargeback reports (optional)
To include PayPal transactions into chargeback reports (optional) generated by Sherlock's, select the following option:
![screenshot showing option to check: generate consolidated reports for all accounts](../../resources/images/en/paypal-integration/PayPal-account-chargeback-reports.png)
Making a PayPal payment
Sherlock's offers you two solutions to integrate the PayPal mean of payment:
- Sherlock’s Paypage which directly acts as the payment interface with clients via their web browser.
- Sherlock’s 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](../../resources/images/en/paypal-integration/ProcessPayment-PayPal.png)
Making a PayPal payment with Sherlock’s Paypage
The payment process for Sherlock’s Paypage is described below:
![diagram representing the kinematics of a Paypal payment with the Sips Paypage connector](../../resources/images/en/paypal-integration/ProcessPaypage-PayPal.png)
Setting the payment request
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". |
Analysing the response
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).paymentMeanBrand =
PAYPALpaymentMeanType =
WALLETresponseCode =
00 |
You can deliver the order. |
Acquirer refusal | acquirerResponseCode = (cf.
the Data Dictionary).responseCode =
05 |
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 =
60responseCode =
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.
Managing refusals
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 Sherlock's 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.
Making a PayPal payment with Sherlock’s Office
The payment process for Sherlock’s Office is described below:
![diagram representing the kinematics of a Paypal payment with the Sips Office connector](../../resources/images/en/paypal-integration/ProcessOffice-PayPal.png)
Initialising a payment (PaymentProviderInitialize)
The initialisation of a PayPal payment is made by calling the paymentProviderInitialize method.
Payment initialisation request
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". |
Payment initialisation response
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.paymentMeanBrand =
PAYPALresponseCode =
00redirectionData = 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).responseCode =
05 |
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.
Redirecting the customer to the PayPal website
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 redirection_data and message_version, also obtained in the response to the payment initialisation. Here is an example of redirection form.
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 |
Finalising a payment (PaymentProviderFinalize)
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.
Payment finalisation request
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). |
Payment finalisation response
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).paymentMeanBrand =
PAYPALresponseCode =
00transactionStatus = (cf. the
Data Dictionary). |
You can deliver the order. |
Acquirer refusal | acquirerResponseCode = (cf.
the Data Dictionary).responseCode =
05 |
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.
Retrieving the customer information (optional)
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.
Customer information retrieval request
Below is a list of fields that must be populated for this method:
Field name | Remarks/rules |
---|---|
redirectionData | Redirection data. |
messageVersion | Message version. |
Customer information retrieval response
Field name | Remarks/rules |
---|---|
paymentMeanData.paypal.payerId | Customer unique ID (PayPal data). |
paymentMeanData.paypal.payerStatus | Customer status (PayPal data).
|
paymentMeanData.paypal.payerBusiness | Customer brand name. |
paymentMeanData.paypal.paymentStatus | Payment status (PayPal data).
|
paymentMeanData.paypal.payerSuffix | Customer suffix |
paymentMeanData.paypal.deliveryAddressStatus |
|
Managing your PayPal transactions
Available cash operations
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 Sherlock's
response code "12" despatch. |
Duplication | V | See the paragraph Duplicating a PayPal transaction. |
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](../../resources/images/en/paypal-integration/ProcessCashManagement-PayPal.png)
Duplicating a PayPal transaction
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
Duplication marking
To mark the transaction as eligible for duplication, you must specify it as such in the creation message sent to Sherlock's by populating the thepaymentMeanData.paypal.dupFlag field with the "true" value.
Description
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.
Type
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).
Customisation
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.
Viewing your PayPal transactions
Reports
The reports provided by Sherlock's 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 |
Sherlock's Gestion
You can view your PayPal transactions and perform various cash management operations with Sherlock's Gestion.
Here are the details of a PayPal transaction. Some specific information is displayed such as PayPal authorisation number: