Introduction
Worldline 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 Worldline 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 Worldline Sips. Cet identifiant est unique pour toute la durée de l’inscription du commerçant sur Worldline 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 à Worldline Sips lors de l’inscription de votre identifiant marchand à l’offre Worldline 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. |
Ce qui ne change pas avec Worldline 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 Worldline Sips et format Versions de 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 - 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 Worldline Sips 1.0 et Worldline 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 |
| 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 |
| 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 (Worldline Sips 2.0) et le champ processing_response_code (Worldline Sips 1.0) :
| Code | Signification processingResponseCode (Worldline Sips 2.0) | Signification processing_response_code (Worldline 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 Worldline Sips classique (champ responseCode).
Différence entre les valeurs possibles du champ officeBatchResponseCode (Worldline Sips 2.0) et le champ office_batch_response_code :
| Codes | Signification officeBatchResponseCode (Worldline Sips 2.0) | Signification office_batch_response_code (Worldline 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 Worldline 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 Worldline Sips 2.0 effectuée, vous n’aurez plus besoin d’utiliser vos fichiers Batch Worldline Sips 1.0.
A terme, une suppression de votre / vos boutiques Worldline Sips 1.0 pourra être envisagée.
