Introduction
Sogenactif 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 échelonné, …).
L’objectif du présent document est d’expliquer la migration Sogenactif Office Batch 1.0 vers Sogenactif Office Batch 2.0.
A qui s’adresse ce document
Ce document est à destination des commerçants disposant de l’offre Sogenactif 1.0.
Pour connaître tous les détails de l’utilisation de Sogenactif Office Batch 2.0, merci de vous référer aux documents Guide d'intégration Sogenactif Office Batch XML et Guide d'intégration Sogenactif Office Batch CSV.
Contacter l'assistance
Pour toute question ou demande d’assistance technique, vous pouvez contacter le support Sogenactif habituel au 0 825 090 095 (0,15€/min + prix appel - tarif au 02/11/2022) du lundi au vendredi, de 9h à 19h, hors jours fériés, ou écrire à supportsogenactif@worldline.com en précisant votre n° de contrat VAD ou MID pour une prise en charge de votre demande plus efficace.
Principe
Choix du mode transactionID ou transactionReference
Par défaut, Sogenactif Office Serveur 2.0 utilise un transactionReference pour identifier une transaction vers le serveur Sogenactif. Cet identifiant est unique pour toute la durée de l’inscription du commerçant sur Sogenactif, 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 à Sogenactif lors de l’inscription de votre identifiant marchand à l’offre Sogenactif 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 Sogenactif 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 [Sogenactif 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 Sogenactif 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 Sogenactif 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 Sogenactif Office Batch 2.0 existe soit en XML soit en CSV.
Comment passer de Sogenactif Office Batch 1.0 a Sogenactif 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 à Sogenactif Office Batch.
Choix du format Sogenactif 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 Guide d'intégration Sogenactif Office Batch XML.
- Au format CSV. Pour plus de détails, veuillez vous référer à la documentation Guide d'intégration Sogenactif Office Batch CSV.
Les échanges avec Sogenactif Office Batch 2.0
Les mêmes règles que pour Sogenactif Office Batch 1.0 sont appliquées :
- Votre compte FTPS ou SFTP qui vous a été fourni par SG pour faire du Sogenactif 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 SG exécutent une vérification de l'adresse IP du commerçant.
- SG 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 Sogenactif Office Batch 2.0.
- Revoir le traitement de ses fichiers réponses au format Sogenactif Office Batch 2.0.
- Utiliser l’environnement de recette client pour tester les applications Sogenactif Office Batch 2.0 avec un identifiant de connexion mis à disposition.
- Faire une demande d’accès en production.
- Supprimer les références à Sogenactif Office Serveur 1.0 sur son site (certificat, composants, fichiers paramètres, fichiers exécutables) une fois la migration totalement terminée.
Ce qui change avec Sogenactif Office Batch 2.0
Structure du fichier
Le fichier Sogenactif Office Batch 2.0 est constitué de quatre parties successives ; FILE TYPE, HEADER, BODY, END
Sur Sogenactif 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 Sogenactif 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 Guide d'intégration Sogenactif Office Batch XML et Guide d'intégration Sogenactif Office Batch CSV pour plus d’information.
Exemple :
Exemple de type de fichier sur Sogenactif Office Batch 1.0 Exemple de type de fichier sur Sogenactif 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 Sogenactif Office Batch 2.0 sont différentes de celle en 1.0 :
Version Sogenactif et format Versions de Sogenactif Office Batch Sogenactif 1.0 Sogenactif 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 Sogenactif 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 Sogenactif 1.0 et Sogenactif 2.0.
| Définition de l’opération effectuée via le service Office | Nom de l’opération dans Sogenactif Office Batch 1.0 - version 2.1 | Nom de l’opération dans Sogenactif 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 Sogenactif Office Batch.
Ces codes réponses sont retournés dans le champ processingResponseCode sur Sogenactif Office Batch 2.0. Il correspond au processing_response_code de Sogenactif 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 (Sogenactif 2.0) et le champ processing_response_code (Sogenactif 1.0) :
| Code | Signification processingResponseCode (Sogenactif 2.0) | Signification processing_response_code (Sogenactif 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 Sogenactif Office Batch. | Fichier invalide : Ces codes concernent les versions plus anciennes de Sogenactif 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 Sogenactif Office Batch 2.0, qui correspond au champ office_batch_response_code sur Sogenactif 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 Sogenactif classique (champ responseCode).
Différence entre les valeurs possibles du champ officeBatchResponseCode (Sogenactif 2.0) et le champ office_batch_response_code :
| Codes | Signification officeBatchResponseCode (Sogenactif 2.0) | Signification office_batch_response_code (Sogenactif 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 Sogenactif Office Batch/non lié au remettant déclaré dans l'en-tête. | Boutique non inscrite à Sogenactif 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 Sogenactif 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 Sogenactif Office Batch 2.0.
Passage en production
Via votre nouvelle boutique Sogenactif 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 Sogenactif 2.0 effectuée, vous n’aurez plus besoin d’utiliser vos fichiers Batch Sogenactif 1.0.
A terme, une suppression de votre / vos boutiques Sogenactif 1.0 pourra être envisagée.
