Introduction

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 on despatch, deferred payment, recurring payment, payment in instalments, etc.).

The purpose of this document is to explain the Sips Office Batch 1.0 migration to the Sips Office Batch 2.0.

Who does this document target?

This document is intended for merchants having the WL Sips 1.0 offer.

For full details on of the WL Sips 2.0 payment pages customisation, please refer to the Sips Office Batch XML and the Sips Office Batch CSV integration guides documents.

Contacting the support

For any technical question or request for assistance, our services are available:

  • by telephone at: +33 (0) 811 10 70 33
  • by e-mail: sips@worldline.com

In order to facilitate the processing of your requests, please provide your merchantId (15-digit number).

Principle

TransactionID or transactionReference mode choice

By default, Sips Office 2.0 uses a transactionReference to identify a transaction to the WL Sips server. This identifier is unique for the duration of the merchant registration on WL Sips , it is not reusable for another payment transaction for example.

If you want to stay in transactionID/transactionDate mode, you must make a request to WL Sips when registering your Merchant ID to offer WL Sips 2.0 so that the configuration of your Merchant ID is consistent with the expected.

The fields to be used in the payment request will therefore be:

transactionReference AN35 Transaction unique identifier

or

s10TransactionId N6 transactionReference is the default method to identify a transaction.
s10TransactionIdDate N8 (YYYYMMDD) s10TransactionId is an alternative to identify a transaction, remaining compatible with the WL Sips 1.0. The couple s10TransactionId / s10TransactionIdDate ensures the uniqueness of the transaction.

What does not change with WL Sips 2.0

  • No change in a request and response files naming:

    • The request file must be transmitted in an archive in ZIP format. The archive must be named OFBREQxx.ZIP . The file must respect the [ Sips Office Batch ] naming [Alias]. [Date]. [Time]. [File Format]
    • The response file is transmitted in an archive in ZIP format. The name of this archive is OFBREPxx . [Day]. [Month]. [Year] .ZIP. The name of the file contained in this archive is formally OFFUBZ.OFFBAREP [Alias]. [Date] - [Time]. [File Format].
  • Your existing sFTP account for batching through your 1.0 shop can also be used for your 2.0 shop. The name of the request and response files for your new 2.0 shop will be incremented by 1. Example: You are using Sips Office Batch 1.0 on a 1.0 shop, your request and response files are named OFBREQ01 and OFBREP01 . After activating Sips Office Batch on your new 2.0 shop, the request and response files attached to this shop will be named OFBREQ02 and OFBREP02 .
  • The Sips Office Batch 2.0 format exists in either XML or CSV.

How to switch from Sips Office Batch 1.0 to Sips Office Batch 2.0

Prerequisites

The knowledge of file transfer protocols and standards of programming languages practiced today, such as Java, PHP or .Net, is needed to develop the connection to Sips Office Batch .

Sips Office Batch 2.0 format Choice

You must determine in which format you want to build your Batch file:

  • In XML format. For more details, please refer to the Sips Office Batch XML Integration guide documentation.
  • In CSV format. For more details, please refer to the Sips Office Batch CSV Integration guide documentation.

Exchanges with Sips Office Batch 2.0

The same rules as for Sips Office Batch 1.0 are applied:

  • Your FTPS or SFTP account that was provided by Worldline for Sips Office Batch 1.0 can be used to batch with your 2.0 shops.
  • This account must be the same for request and response files, but there are restrictions on the file name.
  • In addition to username and password checks, Worldline SFTP and FTPS servers perform a verification of the merchant's IP address.
  • Worldline renames the response file with a different name of the request file.
  • After a given period (1 week), the response files are deleted from the FTPS or SFTP accounts, even if they have not been downloaded.

What the merchant must do?

  • Decide on the BATCH file format (XML or CSV).
  • Decide to stay with transactionID management or go to transactionReference.
  • Review the structure of his request files to be compatible with Sips Office Batch 2.0.
  • Review the processing of his response files in Sips Office Batch 2.0 format
  • Use the customer recipe environment to test Sips Office Batch 2.0 applications with an available login ID.
  • Make an access request in production
  • Delete references to Sips Office 1.0 on his website (certificate, components, settings files, executable files) once the migration is complete.

What does change with Sips Office Batch 2.0?

File structure

  • The Sips Office Batch 2.0 file consists of four successive parts; FILE TYPE, HEADER, BODY, END.

    On Sips Office Batch 2.0, the "version" field has been added at the "file type" level in the request and response file.

    The FORMAT and VERSION fields (which do not exist on SOB 1.0) are mandatory on Sips Office Batch 2.0. Indeed, on SOB 2.0, these fields depend on the type of service called:

    Format Version Service description
    office Must have the value 10 Transactions and cash transactions acceptance
    token Must have the value 1 PANs tokenisation and detokenisation
    fraud Must have the value 2 Fraud management
    wallet Must have the value 3 Management of payment details in the wallet used in the case of Oneclick and subscription.

    Please refer to the Sips Office Batch XML Integration guide and Sips Office Batch CSV Integration guide documents for more information.

    Example :

    Sample file type on Sips Office Batch Sips 1.0 Sample file type on Sips Office Batch Sips 1.0

    In the XML format :

    <file type="request" format="office" >

    In the CSV format:

    FILE : request:office

    (fields separated by « : » in the format CSV SOB 1.0)

    In the XML format:

    <file type="request" format="office" version=" 10" >

    In the CSV format:

    FILE ;request ;office ;10

    (fields separated by « ; » in the format CSV SOB 2.0)

    • Sips Office Batch 2.0 versions are different from 1.0:
    Version WL Sips and format Versions Sips Office Batch WL Sips 1.0 WL Sips 2.0 XML CSV
    01 V X V X
    02 V X V X
    2.1 V X V V
    4 X V V V
    5 X V V V
    6 X V V V
    • In Sips Office Batch 2.0 in XML format, each attribute is between tags (<> </>).

Fields names/operations

  • The name of the fields in 2.0 are different. For more details, please refer to the Data 1.0 and 2.0 correlation guide document.
  • The names of the possible operations via the Office service are different between WL Sips 1.0 and WL Sips 2.0.
Definition of the operation performed via the Office service Name of the operation in Sips Office Batch 1.0 - version 2.1 Name of the operation in Sips Office Batch 2.0 - version 10
Format XML Format CSV Format XML Format CSV
Completes a card transaction with an authorisation request. author AUTHOR cardOrder CARDORDER
Cancellation of a transaction before sending to the bank. cancel CANCEL cancel CANCEL
Credits the cardholder account (without reference to an existing transaction, unlike repayments). creditholder CREDITHOLDER credit CREDIT
Duplicates an existing transaction while protecting the details of the original transaction. duplicate DUPLICATE duplicate DUPLICATE
Forcing a transaction following a consultation advice ADVICE force FORCE
Full or partial refund of a transaction (after sending to the bank). credit CREDIT refund REFUND
Validation of a transaction to trigger the sending to the bank. validate VALIDATE validate VALIDATE
Completes a transaction using the merchant wallet as a payment method. walletorder WALLETORDER walletOrder WALLETORDER
Completes a transaction using the bank information to perform a direct debit. via the DATA : sdd_mandate_id field via the DATA : SDD_MANDATE_ID field directDebitOrder DIRECTDEBIT ORDER
Creating a new transaction by using the details of a previous transaction. This operation is similar to the duplication but with limitations. N/A N/A recycle RECYCLE
Accepts the challenge of a transaction. N/A N/A acceptChallenge ACCEPT CHALLENGE
Refuse the challenge of a transaction. N/A N/A refuseChallenge REFUSE CHALLENGE
Credits the cardholder's account by using the merchant's wallet card of the customer without reference to an existing transaction. N/A N/A walletCredit WALLETCREDIT

Analysis of errors when checking the file

There are several levels of response codes when processing a file by Sips Office Batch .

These response codes are returned in the processingResponseCode field on Sips Office Batch 2.0. It corresponds to the processing_response_code of Sips Office Batch 1.0.

Several global checks are performed before the file is processed. If any of these checks fail, the file is completely denied ( processingResponseCode is neither 00 nor 01).

The response file returned contains the global result code of the processing in the field processingResponseCode in the file header.

The summary of the possible values of the processingResponseCode field ( WL Sips 2.0) and the processing_response_code field ( WL Sips 1.0):

Code ProcessingResponseCode ( WL Sips 2.0) Significance Processing_response_code ( WL Sips 1.0) significance
00 File processed correctly. The file contains the list of operations. File processed correctly: the file contains the list of operations.
01 File processed correctly. An operation has been associated with a merchant who is not related to the remitter ID. The officeBatchResponseCode field will be set to 80 by the operation. File processed correctly: one of the merchants of the operations was not related to the remitter declared in the header. The incriminated operation (s) will have the office_batch_response_code " field populated with "80".
02 File already processed. The sequence number of the file is less than it should be. The correct number is sent in the message that describes the error. File already processed: the sequence number of the file is less than the value it should have. The correct number is sent in the error description message.
03 Sequence break in the sequence number of the file. The sequence number of the file is greater than it should be. The correct number is sent in the message that describes the error. Sequence break in the sequence number of the file: the sequence number of the file is greater than the value it should have. The correct number is sent in the error description message.
04 Technical problem. Internal problem Technical problem. Internal problem.
05 File too big File too big: the maximum size of a query file is 100 MB
06 The number of operations exceeds the maximum allowed amount. The maximum number of operations has been reached. Number of transactions exceeds the maximum allowed. The maximum number of transactions is 20 000.
07 The number of operations counted is different from the number indicated in the nbRecord field. Number of transactions exceeds the maximum allowed. The maximum number of transactions is 20 000.
08 Double operation Duplicate of an operation: one of the operations is duplicate (merchant_id + merchant_country + transaction_id + transaction_date) - This rule does not apply to Duplicate.
09 Invalid registration N/A
10 Invalid file format. The file format is invalid (the description of the error will be returned in the "error details" tag). Invalid file format The file format is invalid (the description of the error will be returned in the error-details tag).
11 Invalid delivering. The remitter declared in the header is invalid. Invalid remitter: the remitter declared in the header is invalid.
Other codes Invalid file (these codes are for older versions of Sips Office Batch ). Invalid file (these codes are for older versions of Sips Office Batch ).

Analysis of errors caused by an operation

Each operation is considered to be independent. Each operation has its own stored response code ( officeBatchResponseCode field on Sips Office Batch 2.0, which corresponds to the office_batch_response_code field on Sips Office Batch 1.0). The code indicates the field that is causing the problem.

If an operation fails, the processing is not interrupted. The operation is denied with the conventional WL Sips response code ( responseCode field).

The differences between the possible values of the officeBatchResponseCode field ( WL Sips 2.0) and the office_batch_response_code field:

Codes OfficeBatchResponseCode ( WL Sips 2.0) significance Office_batch_response_code ( WL Sips 1.0) significance
00 No one (all fields are correct.) OK
01 merchantId error Merchant_id error
02 N/A Merchant_country error
03 transactionReference error Transaction_id error
04 merchantTransactionDateTime error Transaction_date error
05 amount error Amout error
06 captureDay error Capture_day error
07 captureMode error Capture_mode error
08 operationAmount error Card_number error
09 operationOrigin error Card_type error
10 N/A Card_validity error
11 currencyCode error Currency_code error
12 customerIpAddress error Customer_ip_address error
13 customerEmail error cvv_flag error
14 customerId error cvv_key error
15 N/A Data error
16 orderId error Order_id error
17 orderChannel error Order_channel error
18 transactionOrigin error Payment_pattern error
19 returnContext error Return_context error
20 fromTransactionReference error From_transaction_id error
21 cardExpiryDate error From_transaction_date error
22 cardNumber error Bank_number error
23 cardCSCValue error N/A
24 cardEffectiveDate error N/A
25 cardSeqNumber error N/A
26 paymentMeanBrand error N/A
27 authorisationId error N/A
28 merchantWalletId error N/A
29 paymentMeanId error N/A
30 paymentPattern error N/A
31 number error N/A
32 statementReference error N/A
33 panType error N/A
34 mandateId error N/A
35 valueDate error N/A
36 paymentMeanAlias error N/A
37 account error N/A
38 bankCode error N/A
39 transactionActors error N/A
45 Date fields format error N/A
46 settlementMode error N/A
47 comment error N/A
48 validationIndicator error N/A
50 s10TransactionId error N/A
51 s10TransactionIdDate error N/A
52 s10FromTransactionId error N/A
53 s10FromTransactionIdDate error N/A
54 fraudData error N/A
55 riskManagementDynamicParam error N/A
56 riskManagementDynamicValue error N/A
57 riskManagementDynamicSettingList error N/A
58 fraudListReason error N/A
59 fraudListType error N/A
60 fraudListLevel error N/A
61 fraudListElementType error N/A
62 fraudListElementValue error N/A
63 lastRecoveryIndicator error N/A
80 Unregistered merchant for Sips Office Batch / unrelated remitter declared in the header. Shop not registered at Sips Office Batch / unrelated remitter declared in the header.

Test on the recipe environment

Beforehand, you must apply for the creation of a test shop. During this request, you must specify that you want to test the Sips Office Batch 2.0 solution. Indeed, a configuration of the recipe shop is necessary so that the exchange of files between our server and your sFTP account can be done.

The goal of this recipe phase is to validate that the file structure and the syntax of the requests are correct, and to familiarise you with Sips Office Batch 2.0.

Transition to the production

Via your new WL Sips 2.0 production shop, start by submitting a file containing a limited number of operations to validate the transition to the production. Check in the response file that all the operations have run well:

  • Monitor the acceptance rate (number of responseCode 00 / total number of operations).
  • Check the nature of non-bank refusals:
    • Technical problem: responseCode 90, 97, 99
    • Acquirer fraud: responseCode 34

Once you migrate all your Office Batch operations to Sips 2.0, you will no longer need to use your Batch WL Sips 1.0 files.

In the long term, a removal of your WL Sips 1.0 shop(s) may be considered.