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.

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.

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

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.

The following fields have a particular behaviour:

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

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

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

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.

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:

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.

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.

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.

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.

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

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.