Introduction
Worldline 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 Worldline Sips 1.0 offer.
For full details on of the Worldline 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 Worldline Sips server. This identifier is unique for the duration of the merchant registration on Worldline 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 Worldline Sips when registering your Merchant ID to offer Worldline 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. |
What does not change with Worldline 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 test 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 Worldline Sips and format Versions Sips Office Batch Worldline Sips 1.0 Worldline 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 Worldline Sips 1.0 and Worldline 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 |
| 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 |
| 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 (Worldline Sips 2.0) and the processing_response_code field (Worldline Sips 1.0):
| Code | ProcessingResponseCode (Worldline Sips 2.0) Significance | Processing_response_code (Worldline 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 Worldline Sips response code (responseCode field).
The differences between the possible values of the officeBatchResponseCode field (Worldline Sips 2.0) and the office_batch_response_code field:
| Codes | OfficeBatchResponseCode (Worldline Sips 2.0) significance | Office_batch_response_code (Worldline 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 test 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 test 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 Worldline 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 Worldline Sips 1.0 files.
In the long term, a removal of your Worldline Sips 1.0 shop(s) may be considered.
