Introduction

WL Sips est une solution de paiement de commerce électronique multicanale sécurisée conforme à la norme PCI DSS. Elle vous permet d’accepter et de gérer des transactions de paiement en prenant en compte les règles métiers liées à votre activité (paiement à la livraison, paiement différé, paiement récurrent, paiement en plusieurs fois , …).

L’objectif du présent document est d’expliquer la migration Sips Office Batch 1.0 vers Sips Office Batch 2.0.

A qui s’adresse ce document

Ce document est à destination des commerçants disposant de l’offre WL Sips 1.0.

Pour connaître tous les détails de l’utilisation de Sips Office Batch 2.0, merci de vous référer aux documents Sips Office Batch XML et Sips Office Batch CSV .

Principe

Choix du mode transactionID ou transactionReference

Par défaut, Sips Office 2.0 utilise un transactionReference pour identifier une transaction vers le serveur WL Sips . Cet identifiant est unique pour toute la durée de l’inscription du commerçant sur WL Sips , il n’est pas réutilisable pour une autre transaction de paiement par exemple.

Si vous souhaitez rester en mode transactionID / transactionDate , vous devez en faire la demande à WL Sips lors de l’inscription de votre identifiant marchand à l’offre WL Sips 2.0 afin que la configuration de votre identifiant marchand soit conforme à l’attendu.

Les champs à utiliser dans la requête de paiement seront donc :

transactionReference AN35 Identifiant unique de la transaction

ou

s10TransactionId N6 TransactionReference est le moyen par défaut d’identifier une transaction.
s10TransactionIdDate N8 (YYYYMMDD) s10TransactionId est une alternative pour identifier une transaction, en restant compatible avec WL Sips 1.0. Le couple s10TransactionId / s10TransactionIdDate assure l’unicité de la transaction.

Ce qui ne change pas avec WL Sips 2.0

  • Pas de modification au niveau du nommage des fichiers requête et réponse ;

    • Le fichier requête doit être transmis dans une archive au format ZIP. L’archive doit se nommer OFBREQxx.ZIP . Le fichier doit respecter le nommage [ Sips Office Batch ].[Alias].[Date].[Heure].[Format fichier].
    • Le fichier réponse est transmis dans une archive au format ZIP. Le nom de cette archive est OFBREPxx .[Jour].[Mois].[Année].ZIP. Le nom du fichier contenu dans cette archive a pour formalisme OFFUBZ.OFFBAREP .[Alias].[Date]-[Heure].[Format du fichier].
  • Votre compte sFTP existant pour effectuer du batch via votre boutique 1.0 peut également être utilisé pour votre boutique 2.0. Le nom des fichiers requête et réponse pour votre nouvelle boutique 2.0 sera incrémentée de 1. Exemple : vous utilisez Sips Office Batch 1.0 sur une boutique 1.0, vos fichiers requête et réponse sont nommés OFBREQ01 et OFBREP01 . Suite à l’activation de Sips Office Batch sur votre nouvelle boutique 2.0, les fichiers requête et réponse rattachés à cette boutique seront nommés OFBREQ02 et OFBREP02 .
  • Le format Sips Office Batch 2.0 existe soit en XML soit en CSV.

Comment passer de Sips Office Batch 1.0 a Sips Office Batch 2.0

Prérequis

Une connaissance des protocoles de transfert des fichiers ainsi qu'une connaissance des standards relatifs aux langages de programmation pratiqués aujourd'hui, tels que Java, PHP ou .Net, est nécessaire pour développer la connexion à Sips Office Batch .

Choix du format Sips Office Batch 2.0

Vous devez déterminer sous quel format vous souhaiter construire votre fichier Batch :

  • Au format XML. Pour plus de détails, veuillez vous référer à la documentation Sips Office Batch XML .
  • Au format CSV. Pour plus de détails, veuillez vous référer à la documentation Sips Office Batch CSV .

Les échanges avec Sips Office Batch 2.0

Les mêmes règles que pour Sips Office Batch 1.0 sont appliquées :

  • Votre compte FTPS ou SFTP qui vous a été fourni par Worldline pour faire du Sips Office Batch 1.0 peut être utilisé pour effectuer du batch avec vos boutiques 2.0
  • Ce compte doit être le même pour les fichiers de requêtes et les fichiers de réponses, mais des restrictions s'appliquent quant au nom du fichier.
  • En plus des vérifications de nom d'utilisateur et de mot de passe, les serveurs SFTP et FTPS de Worldline exécutent une vérification de l'adresse IP du commerçant.
  • Worldline donne au fichier de réponses un nom différent de celui du fichier de requêtes.
  • Après une période donnée (1 semaine), les fichiers de réponse sont supprimés des comptes FTPS ou SFTP, même s'ils n'ont pas été téléchargés.

Ce que doit faire le commerçant

  • Décider du format de fichier BATCH (XML ou CSV).
  • Décider de rester avec la gestion du transactionID ou passer au transactionReference.
  • Revoir la structure de ses fichiers requêtes pour qu'ils soient compatibles avec Sips Office Batch 2.0.
  • Revoir le traitement de ses fichiers réponses au format Sips Office Batch 2.0.
  • Utiliser l’environnement de recette client pour tester les applications Sips Office Batch 2.0 avec un identifiant de connexion mis à disposition.
  • Faire une demande d’accès en production.
  • Supprimer les références à Sips Office 1.0 sur son site (certificat, composants, fichiers paramètres, fichiers exécutables) une fois la migration totalement terminée.

Ce qui change avec Sips Office Batch 2.0

Structure du fichier

  • Le fichier Sips Office Batch 2.0 est constitué de quatre parties successives ; FILE TYPE, HEADER, BODY, END

    Sur Sips Office Batch 2.0, le champ « version » a été ajouté au niveau du « file type » dans le fichier requête et réponse.

    Les champs FORMAT et VERSION (qui n’existent pas sur SOB 1.0) sont obligatoires sur SOB 2.0. En effet, sur Sips Office Batch 2.0, ces champs dépendent du type de service appelé :

    Format Version Description du service
    office Doit avoir la valeur 10 Acceptation des transactions et des opérations de caisse.
    token Doit avoir la valeur 1 Tokenisation et détokenisation des PAN.
    fraud Doit avoir la valeur 2 Gestion de la fraude.
    wallet Doit avoir la valeur 3 Gestion des coordonnées de paiement dans le wallet utilisée dans le cas du oneclick et de l’abonnement.

    Veuillez vous référez aux documents Sips Office Batch XML et Sips Office Batch CSV pour plus d’information.

    Exemple :

    Exemple de type de fichier sur Sips Office Batch 1.0 Exemple de type de fichier sur Sips Office Batch 2.0

    Au format XML :

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

    Au format CSV :

    FILE : request:office

    (champs séparés par des « : » au format CSV SOB 1.0)

    Au format XML :

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

    Au format CSV :

    FILE ;request ;office ;10

    (champs séparés par des « ; » au format CSV SOB 2.0)

  • Les versions Sips Office Batch 2.0 sont différentes de celle en 1.0 :

    Version WL Sips et format Versions de 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
  • En Sips Office Batch 2.0 au format XML, chaque attribut se trouve entre balises (<> </>).

Le nom des champs / opérations

  • Le nom des champs en 2.0 sont différents. Pour plus de détails, veuillez vous référer au document Guide de correspondance des données 1.0 2.0.
  • Le nom des opérations possibles via le service Office est différent entre WL Sips 1.0 et WL Sips 2.0.
Définition de l’opération effectuée via le service Office Nom de l’opération dans Sips Office Batch 1.0 - version 2.1 Nom de l’opération dans Sips Office Batch 2.0 - version 10
Format XML Format CSV Format XML Format CSV
Termine une transaction carte par une demande d'autorisation. author AUTHOR cardOrder CARDORDER
Annulation d'une transaction avant son envoi en banque. cancel CANCEL cancel CANCEL
Crédite le compte du porteur (sans référence à une transaction existante, à la différence des remboursements). creditholder CREDITHOLDER credit CREDIT
Duplication d'une transaction existante tout en protégeant les détails de la transaction initiale. duplicate DUPLICATE duplicate DUPLICATE
Forçage d'une transaction suite à une consultation. advice ADVICE force FORCE
Remboursement total ou partiel d'une transaction (après son envoi en banque). credit CREDIT refund REFUND
Validation d'une transaction pour déclencher son envoi en banque. validate VALIDATE validate VALIDATE
Termine une transaction en utilisant le portefeuille commerçant comme moyen de paiement. walletorder WALLETORDER walletOrder WALLETORDER
Termine une transaction en utilisant les informations bancaires pour effectuer un débit direct. via le champ DATA : sdd_mandate_id via le champ DATA : SDD_MANDATE_ID directDebitOrder DIRECTDEBIT ORDER
Création d’une nouvelle transaction en utilisant les détails d’une transaction précédente. Cette opération est similaire à la duplication mais avec des limites. N/A N/A recycle RECYCLE
Accepter la contestation d’une transaction. N/A N/A acceptChallenge ACCEPT CHALLENGE
Refuser la contestation d’une transaction. N/A N/A refuseChallenge REFUSE CHALLENGE
Crédite le compte du porteur en utilisant la carte client du portefeuille du commerçant sans référence à une transaction existante. N/A N/A walletCredit WALLETCREDIT

L’analyse des erreurs lors de la vérification du fichier

Il y a plusieurs niveaux de codes réponses lors du traitement d'un fichier par Sips Office Batch .

Ces codes réponses sont retournés dans le champ processingResponseCode sur Sips Office Batch 2.0. Il correspond au processing_response_code de Sips Office Batch 1.0.

Plusieurs vérifications globales sont effectuées avant que le fichier ne soit traité. Si l'une de ces vérifications échoue, le fichier est entièrement refusé ( processingResponseCode n'est égal ni à 00 ni à 01).

Le fichier de réponses retourné contient le code de résultat global du traitement dans le champ processingResponseCode présent dans l'en-tête du fichier.

Récapitulatif des valeurs possibles du champ processingResponseCode ( WL Sips 2.0) et le champ processing_response_code ( WL Sips 1.0) :

Code Signification processingResponseCode ( WL Sips 2.0) Signification processing_response_code ( WL Sips 1.0)
00 Fichier traité correctement : Le fichier contient la liste des opérations. Fichier traité correctement : Le fichier contient la liste des opérations.
01 Fichier traité correctement : Une opération a été associée à un commerçant qui n'est pas lié à l'identifiant de remettant. Le champ officeBatchResponseCode sera valorisé à 80 par l'opération.

Fichier traité correctement : L’un des commerçants des opérations n’était pas liés au remettant déclaré dans le l'en-tête.

La/Les opération(s) incriminée(s) auront le champ office_batch_response_code valorisé à « 80 ».

02 Fichier déjà traité : Le numéro de séquence du fichier est inférieur à ce qu'il devrait être. Le numéro correct est envoyé dans le message qui décrit l'erreur. Fichier déjà traité : Le numéro de séquence du fichier est inférieur à la valeur qu'il devrait avoir. Le numéro correct est envoyé dans le message de description de l’erreur.
03 Rupture de séquence dans le numéro de séquence du fichier. Le numéro de séquence du fichier est supérieur à ce qu'il devrait être. Le numéro correct est envoyé dans le message qui décrit l'erreur. Rupture de séquence dans le numéro de séquence du fichier : Le numéro de séquence du fichier est supérieur à la valeur qu'il devrait avoir. Le numéro correct est envoyé dans le message de description de l’erreur.
04 Problème technique. Problème interne Problème technique. Problème interne
05 Fichier trop grand Fichier trop gros : La taille maximale d’un fichier requête est de 100 Mo.
06 Le nombre d'opérations dépasse la quantité maximale autorisée. Le nombre maximal d'opérations a été atteint. Nombre d'opérations dépasse le maximum autorisé. Le nombre maximal d’opération est de 20 000.
07 Le nombre d'opérations compté est différent du nombre indiqué dans le champ nbRecord . Nombre d'opérations comptabilisé différent du nombre indiqué dans le champ nb_record. Vérifier l’attribut « nb_record » de l’élement « end ».
08 Opération en double Doublon d'une opération : L’une des opérations est en double (merchant_id + merchant_country + transaction_id + transaction_date) – Cette règle ne s’applique pas aux Duplicate.
09 Enregistrement invalide N/A
10 Format de fichier invalide : Le format du fichier est invalide (la description de l'erreur sera retournée dans la balise « error details »). Format de fichier invalide : Le format du fichier est invalide (la description de l’erreur sera renvoyée dans la balise « error-details »).
11 Remettant invalide : Le remettant déclaré dans l'en-tête est invalide. Remettant invalide : Le remettant déclaré dans l'en-tête n’est pas valide.
Autres codes Fichier invalide : Ces codes concernent les versions plus anciennes de Sips Office Batch . Fichier invalide : Ces codes concernent les versions plus anciennes de Sips Office Batch .

L’analyse des erreurs causées par une opération

Chaque opération est considérée comme indépendante. Chaque opération a son propre code de réponse stocké (champ officeBatchResponseCode sur Sips Office Batch 2.0, qui correspond au champ office_batch_response_code sur Sips Office Batch 1.0). Le code indique le champ qui est à l'origine du problème.

Si une opération échoue, le traitement n'est pas interrompu. L'opération est refusée avec le code réponse WL Sips classique (champ responseCode ).

Différence entre les valeurs possibles du champ officeBatchResponseCode ( WL Sips 2.0) et le champ office_batch_response_code :

Codes Signification officeBatchResponseCode ( WL Sips 2.0) Signification office_batch_response_code ( WL Sips 1.0)
00 Aucun (tous les champs sont corrects.) OK
01 merchantId error Erreur Merchant_id
02 N/A Erreur merchant_country
03 transactionReference error Erreur transaction_id
04 merchantTransactionDateTime error Erreur transaction_date
05 amount error Erreur amout
06 captureDay error Erreur capture_day
07 captureMode error Erreur capture_mode
08 operationAmount error Erreur card_number
09 operationOrigin error Erreur card_type
10 N/A Erreur card_validity
11 currencyCode error Erreur currency_code
12 customerIpAddress error Erreur customer_ip_address
13 customerEmail error Erreur cvv_flag
14 customerId error Erreur cvv_key
15 N/A Erreur data
16 orderId error Erreur order_id
17 orderChannel error Erreur order_channel
18 transactionOrigin error Erreur payment_pattern
19 returnContext error Erreur return_context
20 fromTransactionReference error Erreur from_transaction_id
21 cardExpiryDate error Erreur from_transaction_date
22 cardNumber error Erreur bank_number
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 Commerçant non enregistré pour Sips Office Batch /non lié au remettant déclaré dans l'en-tête. Boutique non inscrite à Sips Office Batch / non liée au remettant déclaré dans l'en-tête.

Test sur l’environnement de recette

Au préalable, vous devez faire la demande de création d’une boutique de test. Lors de cette demande, il faut préciser que vous souhaitez tester la solution Sips Office Batch 2.0. En effet, un paramétrage de la boutique de recette est nécessaire afin que l’échange de fichiers entre notre serveur et votre compte sFTP puisse s’effectuer.

L’objectif de cette phase de recette est de valider que la structure du fichier et la syntaxe des requêtes sont correctes, et de vous familiariser avec Sips Office Batch 2.0.

Passage en production

Via votre nouvelle boutique WL Sips 2.0 de production, commencez par soumettre un fichier contenant un nombre limité d’opérations afin de valider le passage en production. Vérifiez dans le fichier réponse que toutes les opérations se sont bien déroulées :

  • Surveillez le taux d’acceptation (nombre de responseCode 00/nombre total d’opérations).
  • Vérifiez la nature des refus non bancaires :
    • Problème technique : responseCode 90, 97, 99.
    • Fraude acquéreur : responseCode 34.

Une fois la migration de toutes vos opérations Office Batch sur WL Sips 2.0 effectuée, vous n’aurez plus besoin d’utiliser vos fichiers Batch WL Sips 1.0.

A terme, une suppression de votre / vos boutiques WL Sips 1.0 pourra être envisagée.