Chèque-Vacances Connect integration

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 Chèque-Vacances Connect mean of payment integration into Sherlock's.

Who does this document target?

This document is intended to help you implement the Chèque-Vacances Connect mean 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 prepaid payments on Sherlock's with CB complement

General principles

Sherlock's offers several prepaid means of payment CVCO. The principle is as follows:

Customers enter their chèque vacances data.
If the chèque vacances does not cover the entire amount of the cart, the customers pay the rest with the credit card.

The payment with CB complement is subject to a 3-D Secure payment process. If the card complement is not accepted or the 3-D Secure authentication is not successful, the entire transaction is cancelled and the amount of the prepaid mean of payment is not consumed.

Tip: some prepaid means of payment may impose a minimum and/or maximum usable amount. We advise you to view the concerned prepaid mean of payment General conditions of sale in order to know the details.

Acceptance rules

Available functionalities

Payment channels
Internet	V	Default payment channel
MOTO	X
Fax	X
IVS	X

Means of payment
Immediate payment	V
End-of-day payment	V	Default method
Deferred payment	V	Limited to 6 days.
Payment upon shipping	V	Limited to 6 days.
Payment in instalments	X
Subscription payment	X
Batch payment	X
OneClick payment	X

Currency management
Multicurrency acceptance	X
Currency settlement	X

Payment review

During the payment kinematics, it is possible that we don't receive the expected return (timeout), the status of the transaction can be one of the followings.

TO_CONFIRM_CAPTURE (for an IMMEDIATE payment)
TO_CONFIRM_CREDIT

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

REFUSED
TO_CAPTURE/TO_VALIDATE
CAPTURED
TO_CREDIT

The diagram of the Making a CVCO 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.

Signing your Chèque-Vacances Connect acceptance contract

In order to offer CVCO mean of payment on your website, you have to sign an acceptance contract with the distributor of the mean of payment, namely ANCV. Thereafter, you transmit us the contract number for recording in our information system.

So that the CB complement is proposed to the customer, you also have to send us your secure distance selling CB contract number signed with your bank.

Making a Chèque-Vacances Connect payment

Sherlock's offers you two solutions to integrate the Chèque-Vacances Connect means of payment:

Sherlock’s Paypage which directly acts as the payment interface with customers 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 Chèque-Vacances Connect 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:

Description of the possible statuses for a Chèque-Vacances Connect transaction

Making a payment with Sherlock’s Paypage

The payment process for Sherlock’s Paypage is described below:

Steps of a Chèque-Vacances Connect payment via Paypage

Setting the payment request

The following fields have a particular behaviour:

Field name	Remarks/rules
amount	minimum 2000 (20€)
captureDay	The value sent in the request must be 6 at a maximum. A larger value will be forced to 6.
customerLanguage	Allows to choose the language used on Sherlock's and CB complement payment pages.
paymentPattern	Tհe value sent in the request is ignored. The payment type is forced to ONE_SHOT.
orderId	Mandatory. The field length must not exceed 20 characters.
customerContact.email	Mandatory It's the beneficiary ANCV account.

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` = CVCO `paymentMeanType` = PROVIDER `responseCode` = 00	You can deliver the order.
Pending transaction	`acquirerResponseCode` = (cf. the Data Dictionary). `responseCode` = 60	The transaction is still being processed. You will receive a new response with a final status in 30 minutes.
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.
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.

Making a payment with Sherlock’s Office

The payment process for Sherlock’s Office is described below:

Steps of a Chèque-Vacances Connect (CVCO) payment via Paypage

Initialising a payment (PaymentProviderInitialize)

The payment initialisation is done by calling the method paymentProviderInitialize.

Payment initialisation request

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

Field name	Remarks/rules
merchantReturnUrl	Merchant return URL.
paymentMeanBrand	Must be populated with CVCO.

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

Field name	Remarks/rules
amount	minimum 2000 (20€)
captureDay	The value sent in the request must be 6 at a maximum. A larger value will be forced to 6.
customerLanguage	Allows to choose the language used on Sherlock's and CB complement payment pages.
paymentPattern	Tհe value sent in the request is ignored. The payment type is forced to ONE_SHOT.
orderId	Mandatory. The field length must not exceed 20 characters.
customerContact.email	Mandatory It's the beneficiary ANCV account.

Payment initialisation response

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

Status	Response fields	Action to take
Payment initialisation accepted	`acquirerNativeResponseCode` = 00 `messageVersion` = message version retrieved in response to the payment initialisation. `responseCode` = 00 `redirectionData` = redirection data retrieved in response to the payment initialisation. `redirectionUrl` = redirection URL to the mean of payment 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 their online banking website

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

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

Field name	Remarks/rules
responseCode	Redirection processing 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 means of payment 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 Sherlock's.

Payment initialisation request

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

Field name	Remarks/rules
merchantReturnUrl	Merchant return URL
paymentMeanBrand	Must be populated with CVCO.

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

Field name	Remarks/rules
captureMode	Tհe value sent in the request is ignored. The capture mode is forced to IMMEDIATE.
captureDay	Tհe value sent in the request is ignored. The capture delay is forced to 0.
customerLanguage	Allows to choose the language used on Sherlock's and CB complement pages.
paymentPattern	Tհe value sent in the request is ignored. The payment type is forced to ONE_SHOT.
orderId	Mandatory
customerContact.email	Mandatory

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). `acquirerResponseMessage` = information on the amounts paid by each means of payment. Format = field1:field2:[...]field7 field1 = SPLIT field2 = prepayed payment mean name field3 = prepayed payment reference partner field4 = amount payed with the prepayed payment mean field5 = supplement means of payment field6 = masked PAN field7 = amount payed with the supplement payment mean `paymentMeanBrand` = CVCO `responseCode` = 00 `transactionStatus` = (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.

Managing your transactions

Available cash operations

The following operations are available on transactions:

Cash management
Cancellation	V
Validation	V
Refund	V	Only CB part is reimbursed
Duplication	X

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

Viewing your 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 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

Note: for Chèque-Vacances Connect transactions, the paymentMeanBrand field is populated with the value CVCO.

Note:

The acquirerReconciliationDetail field is displayed on the reconciliation logs of CVCO payment mean.

This data is generated at the time of reconciliation from the information provided by the CVCO acquirer.

The value of this data is the concatenation of seven fields separated by the character ":" which contain detailed information on the amounts paid by each payment mean.

It is structured as follows:

field 1 = SPLIT
field 2 = name of the prepaid payment mean
field 3 = remittance number of the prepaid payment mean
field 4 = amount paid with the prepaid payment mean (with 2 decimal places)
field 5 = additional payment mean
field 6 = remittance number of the additional payment mean
field 7 = amount paid with the additional payment mean (with 2 decimal places)

Sherlock's Gestion

You can view your transactions details and perform various cash management operations with Sherlock's Gestion.