___________________________________________________________________________________________ PAYBOX SERVICES. Centre Espace Sud ? Route d?Elne - 66200 LATOUR BAS ELNE Version 3.50 Page 51 sur 68 tél : 04.68.85.79.90 -fax : 04.68.85.79.99 Produit « PAYBOX Direct Plus » I I - - P PR RE ES SE EN NT TA AT TI IO ON N Le produit ?PAYBOX Direct Plus? est une extension du produit ?PAYBOX Direct?. Il permet d?envoyer une transaction à PAYBOX SERVICES via une trame ?question?, et d?obtenir en retour une trame ?réponse? précisant l?acceptation ou le refus de la requête. La solution retenue est basée sur un principe de partage des données sensibles entre le commerçant et PAYBOX SERVICES afin que les données conservées par chacune des parties soient inexploitables unitairement. Cette évolution du produit ?PAYBOX Direct? permet de répondre parfaitement à la problématique des "achats en 1 clic" (fidélisation et/ou abonnements). A chaque opération, le commerçant devra fournir à PAYBOX SERVICES la partie des données en sa possession, PAYBOX SERVICES les complètera avec la partie des données qu?il conserve afin de traiter l?opération. Tout comme pour le traitement PAYBOX Direct, le principe reste le suivant : 1. Créer une trame « question » (chaîne de caractères sous un certain format), 2. Coder celle-ci par l?intermédiaire d?un module de cryptage PAYBOX SERVICES, 3. L?envoyer via un dialogue socket sur un port de PAYBOX SERVICES prévu à cet effet, 4. Récupérer la trame « réponse » retournée par Paybox après traitement de la transaction, 5. décoder cette dernière (via un module fourni par Paybox) pour interpréter le résultat de la requête. I II I ? ? R RA AP PP PE EL L D DU U C CO ON NT TE EX XT TE E 1. Pas de stockage de données sensibles chez le commerçant ni chez PAYBOX SERVICES 2. L?inscription, la modification, la radiation d?un abonné reste à l?initiative du commerçant. 3. Le déclenchement d?une opération de paiement reste à l?initiative du commerçant que cette opération soit hors ou dans un contexte d?abonnement. ___________________________________________________________________________________________ PAYBOX SERVICES. Centre Espace Sud ? Route d?Elne - 66200 LATOUR BAS ELNE Version 3.50 Page 52 sur 68 tél : 04.68.85.79.90 -fax : 04.68.85.79.99 4. La caractéristique de chaque abonnement (montant, fréquence des paiements, durée ?) est gérée par le commerçant. I II II I - - P PA AY YB BO OX X D DI IR RE EC CT T P Pl lu us s ( (O Op pt ti io on n g ge es st ti io on n a ab bo on nn ne em me en nt ts s) ) a a - - A Ac ct ti io on ns s p po os ss si ib bl le es s La version de production actuelle de PPPS permet aujourd?hui les opérations suivantes : Autorisation seule Autorisation + débit Débit (sur une autorisation pré effectuée) Crédit Annulation (d?une opération pré effectuée) Le produit PPPS étendu permettra en plus d?effectuer les opérations suivantes : Inscription d?un nouvel abonné Modification d?un abonné existant Suppression d?un abonné Autorisation seule d?un abonné Autorisation + débit d?un abonné Débit d?un abonné (sur une autorisation pré effectuée) Crédit sur un abonné Annulation d?une opération sur un abonné b b - - N No ou uv ve el ll le es s o op pé ér ra at ti io on ns s l li ié ée es s à à l l? ?a ab bo on nn ne em me en nt t Lors de l?inscription d?un nouvel abonné, le commerçant devra fournir à PAYBOX SERVICES les mêmes champs que pour la demande d?autorisation ?PAYBOX Direct? actuelle accompagnée de la référence abonné (unique). PAYBOX SERVICES vérifiera l?unicité de la référence abonné, et les différents contrôles de validité (expiration, liste noire ?) et effectuera une demande d?autorisation seule (sans débit), et en cas de réponse positive du centre d?autorisation, inscrira ce nouvel abonné à la liste des abonnés avec une partie du numéro porteur, puis retournera au commerçant l?autre partie du numéro porteur afin de la conserver avec la référence abonné, la date de fin de validité carte, et le CVV. La même opération sera effectuée pour la demande de modification d?un abonné. Pour les opérations de débit, crédit, annulation et suppression d?un abonné, le commerçant devra fournir la référence abonné, la partie du N° porteur en sa possession, la date de fin de validité et le CVV accompagnés des autres champs obligatoires dans le protocole d?échange ?PAYBOX Direct?. ___________________________________________________________________________________________ PAYBOX SERVICES. Centre Espace Sud ? Route d?Elne - 66200 LATOUR BAS ELNE Version 3.50 Page 53 sur 68 tél : 04.68.85.79.90 -fax : 04.68.85.79.99 Le principe ?PAYBOX DIRECT? est de : 1. Créer une trame « question » (chaîne de caractères sous un certain format), 2. Coder celle-ci par l?intermédiaire d?un module de cryptage PAYBOX SERVICES, 3. L?envoyer via un dialogue socket sur un port de PAYBOX SERVICES prévu à cet effet, 4. Récupérer la trame « réponse » retournée par PAYBOX SERVICES après traitement de la transaction, 5. Décoder cette dernière (via un module fourni par PAYBOX SERVICES) pour interpréter le résultat de la requête. Les trames sont formées de champs joints les uns aux autres à la manière de paramètres de type URL. Ainsi, la valeur des champs doit suivre le nom même du champ (en majuscule) séparé par le signe ?=?. Les différents couples (nom champ, valeur) sont séparés par le signe ?&?. Il existe aujourd?hui une DLL pour Windows 32 bits (payboxppps.dll) qui se charge de coder la question, effectuer la demande auprès de PAYBOX SERVICES et de décoder la réponse retournée. c c - - P Pr ro ot to oc co ol le e d d? ?é éc ch ha an ng ge e Les trames sont formées de champs joints les uns aux autres à la manière de paramètres de type URL. Ainsi, la valeur des champs doit suivre le nom même du champ (en majuscule) séparé par le signe ?=?. Les différents couples (nom champ, valeur) sont séparés par le signe ?&?. La trame ?question? devra être cryptée à l?aide d?un module fourni par PAYBOX SERVICES, de la manière suivante : codeppps.exe question_à_coder Le résultat de l?exécution de ce module sera une chaîne cryptée redirigée sur stdout. La trame ?réponse? envoyée par PAYBOX SERVICES devra être décryptée, à l?aide d?un autre module également fourni par PAYBOX SERVICES, de la manière suivante : decodeppps.exe reponse_à_décoder Le résultat de l?exécution de ce module sera une chaîne décryptée redirigée sur stdout. L?extension des deux modules diffère suivant votre système d?exploitation : ?.exe? pour Windows et ?.e? pour les autres O.S. (Unix, Linux?) ___________________________________________________________________________________________ PAYBOX SERVICES. Centre Espace Sud ? Route d?Elne - 66200 LATOUR BAS ELNE Version 3.50 Page 54 sur 68 tél : 04.68.85.79.90 -fax : 04.68.85.79.99 I IV V - - D Dé éf fi in ni it ti io on n d de e l la a t tr ra am me e ? ?Q Qu ue es st ti io on n? ? : : n no om m S Si ig gn ni if fi ic ca at ti io on n t ta ai il ll le e e ex xe em mp pl le e VERSION valeur numérique de la version PAYBOX Direct (valeur par défaut 00104 pour la version ?PAYBOX Direct Plus?, 00103 dans la version actuelle). champ obligatoire. 5 chiffres 00104 DATEQ date et heure d?envoi de la trame (date du jour) sous la forme jjmmaaaahhmmss. (jour mois année heure minute seconde). champ obligatoire. Utilisé dans les requêtes SQL pour la question du type 11 (format AAAAMMJJ) 14 chiffres 13022003103050 TYPE type de demande concernant la transaction : 1 = autorisation, 2 = débit, 3 = autorisation + débit, 4 = crédit, 5 = annulation, 11 = vérification de l?existence d?une transaction, 12 = transaction sans demande d?autorisation, 13 = Modification du montant d?une transaction. 51 = autorisation seule sur un abonné, 52 = débit sur un abonné, 53 = autorisation + débit sur un abonné, 54 = crédit sur un abonné, 55 = annulation d?une opération sur un abonné, 56 = inscription nouvel abonné, 57 = modification abonné existant, 58 = suppression abonné. champ obligatoire 5 chiffres 00003 NUMQUESTION identifiant unique et séquentiel de la requête permettant d?éviter les confusions au niveau des réponses en cas de questions multiples et simultanées (il pourra être remis à zéro chaque jour). 1 <= NUMQUESTION <= 2147483647 champ obligatoire 10 chiffres 0000000001 SITE numéro d?adhérent fourni par la banque du commerçant. champ obligatoire. Utilisé dans les requêtes SQL pour les questions du type 2, 5, 11, 13, 52 et 55 7 chiffres 1999888 (site test) RANG numéro de rang du site fourni par la banque du commerçant. champ obligatoire. Utilisé dans les requêtes SQL pour les questions du type 2, 5, 11, 13, 52 et 55 2 chiffres 99 (site test) CLE clé activée uniquement avec les versions à partie de la 00103 [voir ci après]. champ obligatoire pour tous messages supérieurs ou égales à une version ?00103? 8 caractères 1999888I (site test) IDENTIFIANT champ vide. 10 chiffres à ne pas utiliser pour le moment. MONTANT montant en centimes de la transaction (sans virgule ni point). champ obligatoire sauf pour la question du type 58. Utilisé dans les requêtes SQL pour les questions du type 2, 5, 11, 52 et 55 10 chiffres 0000002530 ___________________________________________________________________________________________ PAYBOX SERVICES. Centre Espace Sud ? Route d?Elne - 66200 LATOUR BAS ELNE Version 3.50 Page 55 sur 68 tél : 04.68.85.79.90 -fax : 04.68.85.79.99 DEVISE Code devise de la monnaie utilisée (978 pour l?euro). champ obligatoire sauf pour la question du type 58 3 chiffres 978 REFERENCE référence du commerçant permettant d?identifier clairement la commande correspondant à la transaction. champ obligatoire sauf pour les questions du type 13, 56, 57 et 58. Utilisé dans les requêtes SQL pour la question du type 11 250 caractères maximum TR364875-lot2a REFABONNE référence du commerçant permettant d?identifier clairement l?abonné correspondant à la transaction. champ obligatoire pour les questions du type 51, 52, 53, 54, 55, 56, 57 et 58. 250 caractères maximum AZERTY1234567 PORTEUR numéro de carte du porteur (client) sans espace, cadré à gauche et complété avec des ??? à droite pour les phases d?inscription ou de modification. Numéro de porteur partiel cadré à gauche dans les autres cas. champ obligatoire pour les questions du type 1, 3, 4, 5, 12, 51, 53, 54, 55, 56 et 57. Non contrôlé pour les questions du type 5 et 55 19 caractères 1111222233334444??? DATEVAL date de fin de validité de la carte porteur au format MMAA. champ obligatoire pour les questions du type 1, 3, 4, 5, 12, 51, 53, 54, 55, 56 et 57 4 chiffres 1002 CVV cryptogramme visuel situé au dos de la carte bancaire. ILL : si illisible. Remarque : Les cartes AMERICAN EXPRESS ont sur leur recto un CIN (Card Identification Number) sur 4 chiffres. 3 ou 4 caractères 123 ACTIVITE indicateur de commerce électronique (ECI) permettant de différencier la provenance des différents flux monétiques envoyés [voir page 54]. 3 chiffres 024 ARCHIVAGE référence d?archivage transmise aux banques des porteurs. Si elle est gérée par la banque concernée, elle pourra alors apparaître sur le relevé de compte du client lui permettant ainsi d?identifier plus facilement l?origine de son achat. 12 caractères maximum boutiquetest DIFFERE Nombre de jours d?attentes avant la mise à disposition de la transaction pour l?envoi à la banque du commerçant (télécollecte) 3 chiffres maximum 000 NUMAPPEL numéro remis par Paybox dans la trame « REPONSE » : ce champ doit être renseigné lors de la prochaine trame ?QUESTION? pour une deman9 de de capture ou d?annulation. Pour les autres types de demande (1, 3 ou 4), ce champ sera vide. champ obligatoire pour les questions du type 2, 5, 13, 52 et 55. Utilisé dans les requêtes SQL pour les questions du type 2, 5, 13, 52 et 55 10 chiffres ___________________________________________________________________________________________ PAYBOX SERVICES. Centre Espace Sud ? Route d?Elne - 66200 LATOUR BAS ELNE Version 3.50 Page 56 sur 68 tél : 04.68.85.79.90 -fax : 04.68.85.79.99 NUMTRANS numéro remis par Paybox dans la trame ?REPONSE? lors de la gestion d?un paiement susceptible d?être envoyé à la banque : ce champ doit être renseigné lors de la prochaine trame ?QUESTION? pour une demande de capture ou d?annulation. Pour les autres types de demande (1, 3 ou 4), ce champ sera vide. champ obligatoire pour les questions du type 2, 5, 13, 52 et 55. Utilisé dans les requêtes SQL pour les questions du type 2, 5, 13, 52 et 55 10 chiffres AUTORISATION numéro d?autorisation fournie par le commerçant suite à un appel phonique auprès de sa banque. valeur utilisée pour les questions du type 1, 3, 13, 51, 56 et 57 10 caractères maximum 130968 PAYS Indication que le code pays doit être retourné lors de la réponse. norme ISO 3166 3 caractères alphabétiques FRA Pour toutes les demandes du type 51, 52, 53, 54, 55, 57 et 58 une inscription préalable de l?abonné est obligatoire. Pour cela, une trame avec le type d?opération 56 devra être envoyé vers le serveur de PAYBOX SERVICES. La création d?un nouvel abonné génère une demande d?autorisation, pour le montant précisé dans la trame, auprès de la banque afin de s?assurer de la validité de la carte. En cas d?acceptation de la part de la banque, l?abonné sera crée au niveau de la base de données de PAYBOX SERVICES mais pas dans le cas contraire. A la suite de la création d?un abonné, il peut être envoyé directement une trame du type 52 (débit sur un abonné) si le montant précisé lors de la trame de création correspond au montant à débiter. S?il ne s?agit pas du même montant, il faudra alors émettre une trame d?autorisation + débit (53) ou une trame autorisation seule (51) suivi d?une trame débit (52). Vérification de l?existence d?une transaction : Pour ce type demande, les rubriques suivantes sont utilisées dans le cadre de la requête au niveau de notre base de données : ? REFERENCE ? MONTANT ? DATEQ Modification du montant d?une transaction : Pour ce type demande, les rubriques suivantes sont utilisées dans le cadre de la requête au niveau de notre base de données : ? SITE ? RANG ___________________________________________________________________________________________ PAYBOX SERVICES. Centre Espace Sud ? Route d?Elne - 66200 LATOUR BAS ELNE Version 3.50 Page 57 sur 68 tél : 04.68.85.79.90 -fax : 04.68.85.79.99 ? NUMAPPEL ? NUMTRANS C?est pourquoi, leur présence et leur contenu doivent être identiques à ce qui est retourné dans la trame retour de la transaction d?origine. Une nouvelle demande d?autorisation sera faite auprès de la banque du commerçant, et en cas d?autorisation de celle-ci, la transaction d?origine sera automatiquement annulée. Les différentes valeurs du champ ACTIVITE : Il s?agit pour la banque de différencier la provenance des différents flux monétiques envoyés ; ceci ayant pour but de renseigner de la manière la plus correcte possible les champs relatifs à l?ECI (Indicateur de Commerce Electronique). Voici les valeurs possibles pour le type d?activité : 020 : non spécifié, 021 : demande par téléphone, 022 : demande par correspondance, 023 : demande par minitel, 024 : demande par internet, 025 : demande par télévision (paiement par démodulateur?), 027 : paiement récurrent, 035 : demande par téléphonie mobile. Le principe de répartition du numéro porteur: Les différentes parties concernées par cette opération ne doivent pas conserver pas de données sensibles (N° porteur). Le principe retenu est donc de répartir les informations contenues dans cette donnée entre les différentes parties, les données conservées par chacune d?entre elles devenant donc inexploitables seules. Nous allons faire conserver à chacune des parties 1 caractère sur 2. Le numéro de porteur retourné par notre serveur est déjà scindé en deux parties et est crypté. C?est cette information que vous devez conservez sans les caractères CR+LF en fin de chaîne. V V - - D Dé éf fi in ni it ti io on n d de e l la a t tr ra am me e ? ?R Ré ép po on ns se e? ? : : En retour PAYBOX SERVICES adresse au commerçant les données suivantes : n no om m S Si ig gn ni if fi ic ca at ti io on n t ta ai il ll le e e ex xe em mp pl le e NUMTRANS numéro de la transaction créée sur Paybox. 10 chiffres 0000563149 NUMAPPEL numéro de la requête gérée sur Paybox. 10 chiffres 0000782653 ___________________________________________________________________________________________ PAYBOX SERVICES. Centre Espace Sud ? Route d?Elne - 66200 LATOUR BAS ELNE Version 3.50 Page 58 sur 68 tél : 04.68.85.79.90 -fax : 04.68.85.79.99 NUMQUESTION identifiant unique et séquentiel de la requête permettant d?éviter les confusions au niveau des réponses en cas de questions multiples et simultanées. 1 <= NUMQUESTION <= 2147483647 10 chiffres 0000000001 SITE numéro d?adhérent fourni par la banque du commerçant. 7 chiffres 1999888 (site test) RANG numéro de rang du site fourni par la banque du commerçant. 2 chiffres 99 (site test) IDENTIFIANT Champ vide. 10 chiffres AUTORISATION numéro d?autorisation délivré par le centre d?autorisation de la banque du commerçant si le paiement est accepté. 10 caractères maximum 168753 CODEREPONSE code réponse concernant l?état de la question traitée : opération acceptée ou refusée [voir ci après les différents codes retour]. 5 chiffres 00007 (date invalide) REFERENCE référence du commerçant permettant d?identifier clairement la COMMANDE correspondant à la transaction. 250 caractères maxi TR364875-lot2a REFABONNE Numéro d?abonné donné dans la trame question. Vide (zéros binaires) en contexte hors abonnement. 250 caractères maxi AZERTY1234567 PORTEUR Numéro porteur partiel rendu par Paybox lors de l?inscription ou de la modification .Vide (zéros binaires) dans les autres cas. 19 caractères maxi COMMENTAIRE messages divers pour information. 100 caractères PAYBOX+PPPS PAYS code pays du porteur de la carte. La valeur ??? sera retournée si le code pays est inconnu. norme ISO 3166 3 caractères alphabétiques FRA V VI I - - L LE ES S C CO OD DE ES S R RE ET TO OU UR R D D? ?O OP PE ER RA AT TI IO ON N : : Le champ ?CODEREPONSE?, dans la trame ?réponse?, renvoie un code correspondant au résultat de la requête traitée par PAYBOX SERVICES. c co od de e S Si ig gn ni if fi ic ca at ti io on n C Co od de e s si ig gn ni if fi ic ca at ti io on n 00000 Opération réussie. 00012 Référence commande invalide 00001 Pour une utilisation d?une version autre que la 00101, un code réponse à 00001 signifie que la connexion au centre d?autorisation a échoué. Vous pouvez dans ce cas là effectuer une nouvelle tentative sur les serveurs de secours ppps1.paybox.com et ppps2.paybox.com. 00013 Cette version n?est plus soutenue 001xx Paiement refusé par le centre d?autorisation [voir explication page 34]. En cas d?autorisation de la transaction par le centre d?autorisation de la banque, le résultat ?00100? sera en fait remplacé directement par ?00000?. 00014 Trame reçue incohérente 00002 Une erreur de cohérence est survenue. 00015 Erreur d?accès aux données précédemment référencées 00003 Erreur Paybox. 00016 Abonné déjà existant (inscription nouvel abonné) ___________________________________________________________________________________________ PAYBOX SERVICES. Centre Espace Sud ? Route d?Elne - 66200 LATOUR BAS ELNE Version 3.50 Page 59 sur 68 tél : 04.68.85.79.90 -fax : 04.68.85.79.99 00004 Numéro de porteur invalide. 00017 Abonné inexistant 00005 Numéro de question invalide. 00018 Transaction non trouvée (question du type 11) 00006 Accès refusé ou site / rang incorrect. 00019 Réservé 00007 Date invalide. 00020 Cryptogramme visuel non présent 00008 Date de fin de validité incorrecte. 00021 Carte non autorisée. 00009 Type d?opération invalide. 00022 Réservé 00010 Devise inconnue 00023 Réservé 00011 Montant incorrect 00099 Incohérence entre la question et la réponse. Refaire une nouvelle tentative ultérieurement. Pour le cas d?un paiement refusé par le centre d?autorisation (CODEREPONSE à 001xx), les « xx » représentent le code renvoyé par le centre. Ce code permet de connaître la raison exacte du rejet de la transaction. Par exemple, pour une transaction refusée pour raison « provision insuffisante », le CODEREPONSE renvoyé sera 00151. Tous les codes sont précisés au paragraphe « IV les codes réponses du centre d?autorisation » (page 28 du manuel disponible en zone téléchargement de www.paybox.com). V VI II I - - U UT TI IL LI IS SA AT TI IO ON N D DE E L L? ?O OU UT TI IL L P PP PP PS S P Pl lu us s ( (o ob bj je et t o ou u d dl ll l) ) : : L?outil PPPS Plus se présente sous forme de DLL API pour Windows ou sous forme d?objet C pour tout autre système d?exploitation (Linux, Unix?). Cet outil permet une intégration simplifiée du produit. En effet, il gère la création et le codage de la trame « question », le dialogue socket ainsi que la réception et le décodage de la trame « réponse ». Ces trois étapes sont gérées indépendamment les unes des autres grâce à des fonctions propres. Il existe tout de même une fonction de plus haut niveau qui gère l?ensemble du traitement. La DLL ainsi que l?objet ont tous deux été développés en C : - la DLL API pour Windows peut être intégrée via différents langages tel que le C++, Visual Basic, Java, FoxPro, Delphi? - l?objet ne peut être intégré uniquement via un programme écrit en C.