Guide de référence de l API pour les Services Web

Transcription

1 Guide de référence de l API pour les Services Web juillet 2014 Version 1.0

2 Le présent manuel et le support électronique qui l accompagne sont des produits exclusifs de Paiements Optimal, S.A.R.L. Leur usage est réservé aux utilisateurs autorisés du produit Paiements Optimal, S.A.R.L. Tous droits réservés. Les renseignements que contient le présent document sont susceptibles d être modifiés sans préavis. Le logiciel décrit dans le présent document est fourni sous licence et ne peut être utilisé ou copié que conformément aux conditions du contrat de licence. Aucune partie du présent manuel ne peut être reproduite ni transférée sous quelque forme que ce soit ou par quelque moyen que ce soit sans le consentement écrit explicite de Paiements Optimal, S.A.R.L. Les autres noms, marques de commerce, et marques déposées appartiennent à leur propriétaire respectif. Paiements Optimal, S.A.R.L. n offre aucune garantie explicite ou implicite concernant ce produit, sa qualité marchande, ou son adéquation à un usage particulier autre que les garanties explicitement décrites dans le contrat de licence du produit. Pour obtenir de plus amples renseignements à ce sujet, veuillez communiquer avec Paiements Optimal, S.A.R.L. Siège social international 3500, boulevard de Maisonneuve Ouest, bureau 700 Montréal (Québec) H3Z 3C1 Canada Tél. : (514) Téléc. : (514) Courriel : info@optimalpayments.com Soutien technique : support@optimalpayments.com Site Web : Bureau du Royaume-Uni Compass House, Vision Park Chivers Way, Histon Cambridge CB24 9AD Royaume-Uni Courriel : info@netbanx.com Soutien technique : support@netbanx.com Site Web : Bureau des États-Unis 1209 Orange Street Wilmington, DE Bureau de Gatineau 75, Promenade du Portage Gatineau (Québec) J8X 2J9 Canada

3 Table des matières 1 Services Web de NETBANX Que sont les Services Web de NETBANX? Les Services Web sont compatibles avec les prélèvements automatiques Les Services Web sont compatibles avec les cartes de crédit Les Services Web sont compatibles avec le service de consultation des données Exigences système Accéder aux WSDL et aux liens NETBANX Prélèvement automatique Carte de crédit Service de consultation des données Tests des Services Web de NETBANX Caractéristiques de sécurité AVS CVD Base de données des éléments négatifs D Secure Utilisation du présent guide Cible Fonctionnalités Symboles Transactions par prélèvement automatique (débit direct) Introduction Exemple.NET Bâtir des requêtes de facturation, de vérification ou de crédit Exemple de facturation C# Diagramme de transaction ddcheckrequestv Éléments de transaction ddcheckrequestv Considérations spéciales relatives aux éléments de prélèvement automatique Création de requêtes updateshippinginfo Exemple de transaction updateshippinginfo C# Diagramme de transaction ddshippingrequestv Éléments de transaction ddshippingrequestv Création de lookuprequest (requêtes de consultation) Exemple de transaction lookuprequest C# Diagramme de transaction ddlookuprequestv Éléments de transaction ddlookuprequestv Création de mandaterequest pour BACS (requêtes de mandat) Guide de référence de l API pour les Services Web 1.0 III

4 juillet 2014 Création de mandaterequest pour SEPA (requêtes de mandat) Exemple de transaction mandaterequest C# Diagramme de transaction ddmandaterequestv Éléments de transaction ddmandaterequestv Création de changestatusrequest (requêtes de modification d état) Exemple de transaction changestatusrequest C# Diagramme de transaction ddchangestatusrequest Éléments de transaction ddchangestatusrequestv Création de updatemandaterequest (mise à jour du mandat) Exemple de transaction updatemandaterequest C# Diagramme de transaction ddupdatemandaterequestv Éléments de transaction ddupdatemandaterequestv Traitement de la réponse Transactions par carte de crédit ou de débit Introduction Exemple.NET Bâtir des requêtes d achat, d autorisation ou de vérification Exemple de transaction d achat C# Diagramme de transaction ccauthrequestv Éléments de transaction ccauthrequestv Paires étiquette/valeur addendumdata Bâtir des requêtes d inversion d autorisation Exemple d une transaction d inversion d autorisation C# Diagramme de transaction ccauthreversalrequestv Éléments de transaction ccauthreversalrequestv Bâtir des requêtes de règlement et de crédit Exemple de règlement C# Diagramme de transaction ccpostauthrequestv Éléments de transaction ccpostauthrequestv Bâtir des requêtes de données mémorisées Exemple d autorisation à partir de données mémorisées C# Diagramme de transaction ccstoreddatarequestv Éléments de transaction ccstoreddatarequestv Bâtir des requêtes d annulation Exemple d annulation de règlement C# Diagramme de transaction cccancelrequestv Éléments de transaction cccancelrequestv Bâtir des requêtes de paiement/crédit indépendant Exemple de paiement C# Diagramme de transaction ccpaymentrequestv Éléments de transaction ccpaymentrequestv Bâtir des requêtes de consultation des données Exemple de consultation des données C# Diagramme de transaction cctxnlookuprequestv IV

5 juillet 2014 Éléments de transaction cctxnlookuprequestv Bâtir des requêtes de consultation d inscription Exemple de consultation d inscription C# Diagramme de transaction ccenrollmentlookuprequestv Éléments de transaction ccenrollmentlookuprequestv Bâtir des requêtes d authentification Exemple d authentification C# Diagramme de transaction ccauthenticaterequestv Éléments de transaction ccauthenticaterequestv Traitement de la réponse Paires étiquette/valeur detail Paires étiquette/valeur pour addendumresponse Codes de devises Transactions du service de consultation des données Introduction WSDL et liens ILS NETBANX Exemple.NET Bâtir des requêtes ILS ILS C# Diagramme de transaction ilslookuprequestv Éléments de transaction ilslookuprequestv1s Traitement de la réponse Diagramme de transaction ilslookupresponsev Contenu de l élément de réponse Détails dans la réponse aux requêtes d autorisation Détails dans la réponse aux requêtes de règlement Détails dans la réponse aux requêtes de crédit Détails dans la réponse aux requêtes de rétrofacturation Détails dans la réponse aux requêtes de prélèvement automatique (débit direct) Codes de motif Codes de motifs de rétrofacturation Codes de motif de requête de récupération Codes de motifs de rétrofacturation et de requête de récupération pour Discover A Utilisation de la méthode HTTP Post Introduction A-1 Requêtes relatives à un prélèvement automatique A-1 facturation/vérification/crédit A-1 Exemple HTML Facturation A-2 updateshippinginfo A-4 Exemple HTML updateshippinginfo A-4 ddlookuprequest A-5 Exemple HTML lookuprequest A-6 Guide de référence de l API pour les Services Web 1.0 V

6 juillet 2014 ddmandaterequest A-7 Exemple HTML mandaterequest A-8 changestatusrequest A-9 Exemple HTML changestatusrequest A-10 updatemandaterequest A-10 Exemple HTML updatemandaterequest A-11 Requêtes relatives à une carte de crédit A-12 Achat, autorisation et vérification A-12 Exemple HTML Autorisation A-13 Inversion d autorisation A-15 Exemple HTML Inversion d autorisation A-16 Règlement et crédit A-16 Exemple HTML Règlement A-17 Autorisation ou achat à partir de données mémorisées A-18 Exemple HTML Autorisation à partir de données mémorisées A-19 Annuler un règlement, un crédit, un paiement, ou un crédit indépendant A-20 Exemple HTML Annuler A-20 Requête de paiement A-21 Exemple HTML Paiement A-22 Consultation des données A-23 Exemple HTML Consultation des données A-24 Consultation d inscription A-25 Exemple HTML Consultation d inscription A-26 Authentification A-27 Exemple HTML Authentification A-28 Requêtes relatives au service de consultation des données A-28 Exemple HTML ILS A-29 HTTP Post Exemples A-30 HTTP Post Réponses aux requêtes A-31 B Codes de réponse Aperçu B-1 Codes de réponse B-1 Codes d action B-21 Codes de refus B-21 C Codes géographiques Codes de province C-1 Codes d état C-2 Codes de pays C-3 VI

7 CHAPITRE 1 Services Web de NETBANX Que sont les Services Web de NETBANX? Les Services Web reposent sur une technologie permettant aux applications de communiquer entre elles d une manière indépendante des plateformes et des langages de programmation. Un Service Web est une interface de logiciel qui décrit une collection d opérations auxquelles on peut accéder sur le réseau à l aide de messages XML uniformisés. Il utilise des protocoles écrits en langage XML pour décrire une opération à exécuter ou des données à échanger avec un autre Service Web. Les Services Web sont bâtis selon des normes ouvertes comme SOAP et WSDL. Les Services Web de NETBANX offrent les avantages suivants : Les marchands peuvent s intégrer facilement à l API des Services Web, en se servant de leur plateforme et de leur langage préférés. Les marchands peuvent automatiser les opérations afin d éviter de saisir les renseignements manuellement à l aide de la page Web de NETBANX. Les marchands peuvent fonctionner indépendamment des modifications et des mises à jour faites sur le site Web de NETBANX. Les Services Web sont compatibles avec les prélèvements automatiques NETBANX prend actuellement en charge les Services Web suivants en ce qui concerne les prélèvements automatiques : Tableau 1-1 : Opérations de prélèvement automatique Opération verify (vérification) charge (facturation) credit (crédit) updateshippinginfo lookuprequest mandaterequest changestatusrequest Description Vous permet de confirmer que le compte bancaire d un client est en règle, sans toutefois retirer de l argent du compte. Vous permet de transférer des fonds du compte bancaire d un client vers votre compte de marchand. Cette transaction se fait en temps réel, bien que le réseau bancaire ne transfère les fonds que trois à cinq jours plus tard. Vous permet de transférer des fonds de votre compte de marchand directement au compte bancaire du client. Cette transaction se fait en temps réel, bien que le réseau bancaire ne transfère les fonds que trois à cinq jours plus tard. Vous permet de transmettre l information d expédition, y compris le numéro de suivi, lorsque vous avez expédié la marchandise pour laquelle vous avez déjà traité une transaction de facturation. Vous permet de produire un rapport à l aide de l API pour une plage de temps que vous précisez, afin de recevoir les données concernant les transactions de charge et de credit par prélèvement automatique qui sont traitées par votre compte de marchand. Vous permet de créer un mandat pour le compte bancaire d un client et de le déposer à sa banque, afin que vous puissiez transférer des fonds du compte bancaire du client vers votre compte commercial. Le réseau bancaire traite généralement le mandat en cinq jours. Vous permet de changer l état d une transaction de facturation, de crédit ou de mandat. Guide de référence de l API pour les Services Web

8 Services Web de NETBANX juillet 2014 Tableau 1-1 : Opérations de prélèvement automatique (suite) Opération updatemandaterequest Description Vous permet de mettre à jour les informations contenues dans un mandat existant. La disponibilité des types d opérations par prélèvement automatique est attribuée aux marchands sur une base individuelle, puisque ce ne sont pas toutes les banques des marchands qui acceptent toutes les opérations. Si vous avez des questions, communiquez avec votre gestionnaire de compte. Les Services Web sont compatibles avec les cartes de crédit NETBANX prend actuellement en charge les Services Web suivants pour les cartes de crédit : Tableau 1-2 : Opérations par carte de crédit Opération Authorization (autorisation) Purchase (achat) Verification (vérification) Authorization Reversal (inversion d autorisation) Credit (crédit) Settlement (règlement) Stored Data Authorization (autorisation à partir de données mémorisées) Stored Data Purchase (achat à partir de données mémorisées) Cancel (annulation) Payment (paiement) Independent Credit (crédit indépendant) Description Vous permet de confirmer qu une carte de crédit existe et que les fonds sont suffisants pour couvrir un achat, sans toutefois régler les fonds dans votre compte de marchand. Autorise et règle un montant demandé sur une carte de crédit. Vous permet d exécuter une vérification AVS ou CVD de la carte de crédit, sans imputer un montant sur cette carte. Vous permet d inverser une partie ou la totalité d une autorisation existante, pourvu qu aucun règlement (complet ou partiel) n ait été traité à l'égard de cette autorisation. Ce type de transaction ne fonctionne pas pour les transactions d'achat ; cette transaction n est utilisée que pour les autorisations. Vous permet d émettre un crédit pour un montant qui a déjà été réglé. Vous permet de régler le montant d une autorisation existante, en créditant le montant autorisé de la carte de crédit à votre compte de marchand. Vous permet d autoriser un montant sur la carte de crédit d un client à l aide des données sur le client qui sont mémorisées dans notre base de données. Vous n avez qu à fournir le minimum de renseignements, ce qui vous permet de gagner du temps et de réduire les efforts. Vous permet d autoriser et de régler un montant sur la carte de crédit d un client à l aide de données sur le client qui sont mémorisées dans notre base de données. Vous n avez qu à fournir le minimum de renseignements, ce qui vous permet de gagner du temps et de réduire les efforts. Vous permet d annuler une transaction de crédit, de règlement, de paiement, ou de crédit indépendant. Vous pouvez annuler une de ces transactions pourvu qu elle soit En attente, ce qui est habituellement le cas avant minuit le jour où la requête est faite. Dans certains cas, vous pouvez trouver des transactions de crédit plus anciennes En attente. Vous permet de créditer un montant sur la carte de crédit d un client. La transaction de paiement n est pas liée à une autorisation existante antérieure ; le montant de la transaction n est donc pas limité de cette manière. Vous permet de créditer un montant sur la carte de crédit d un client. La transaction de crédit indépendant n est pas liée à une autorisation existante antérieure ; le montant de la transaction n est donc pas limité de cette manière. 1-2

9 juillet 2014 Les Services Web sont compatibles avec le service de consultation des données Tableau 1-2 : Opérations par carte de crédit Opération Information Lookup (consultation des données) Enrollment Lookup (consultation d inscription) Authentication (authentification) Description Vous permet de produire un rapport à l aide de l API pour une plage de temps que vous précisez, afin de recevoir les données concernant les transactions traités par un compte de marchand. Vous permet d établir si la carte de crédit du client est inscrite à notre programme 3D Secure. Vous permet d envoyer une requête d authentification afin qu un titulaire de carte inscrit au programme 3D Secure puisse authentifier sa carte auprès de l émetteur de la carte avant que vous traitiez une autorisation. La disponibilité des types d opérations pour les cartes de crédit est attribuée aux marchands sur une base individuelle, puisque ce ne sont pas toutes les banques des marchands qui acceptent toutes les opérations. Si vous avez des questions, communiquez avec votre gestionnaire de compte. Les Services Web sont compatibles avec le service de consultation des données NETBANX prend actuellement en charge les Services Web suivants : Tableau 1-3 : Opération du service de consultation des données Opération Information Lookup Service (service de consultation des données) Description Vous permet de produire un rapport à l aide de l API pour une plage de temps que vous précisez, afin de recevoir les données concernant les autorisations, les règlements, les crédits et les rétrofacturations traités par un compte de marchand. Exigences système L API de SOAP a été testé dans les environnements clients suivants : Tableau 1-4 : Environnements clients Client SOAP Microsoft.NET 1.1 et 2.0 Framework Apache Axis 1.4 Environnement de programmation Microsoft Visual Studio.NET 2003 Java (J2SE 1.4.X et versions plus récentes) Environnement opérationnel Microsoft Windows Server 2003 et Windows XP Linux et Microsoft Windows XP, Server 2003 Apache Axis 2.0 Java (J2SE 1.4.X et 1.5.X) Linux et Microsoft Windows XP, Server 2003 Pour obtenir plus de détails : J2SE ou J2EE ou version plus récente (1.4.X recommandée) Sun Microsystems, Inc. Guide de référence de l API pour les Services Web

10 Services Web de NETBANX juillet 2014 Apache Axis 1.4, The Apache Software Foundation Apache Axis2, 1.2, The Apache Software Foundation Microsoft.NET Framework Version 1.1/2.0 Microsoft Corporation Peu importe le client SOAP que vous choisissez, il doit prendre en charge la messagerie de style documents. Accéder aux WSDL et aux liens NETBANX Prélèvement automatique WSDL : Service Web : Publication HTTP : Carte de crédit WSDL : Service Web : Publication HTTP : Service de consultation des données WSDL : Service Web : Publication HTTP : 1-4

11 juillet 2014 Tests des Services Web de NETBANX Tests des Services Web de NETBANX Après avoir terminé la configuration de votre application orientée Services Web, veuillez communiquer avec notre équipe de soutien technique pour obtenir des instructions relatives au test des appels API. Courriel : support@optimalpayments.com Téléphone : Caractéristiques de sécurité Dans le cas de certaines transactions (achat, par exemple), NETBANX offre des caractéristiques supplémentaires qui permettent au marchand de se prémunir contre l utilisation frauduleuse des cartes. Système de vérification d adresse (AVS) Données de validation des cartes (CVD) Base de données des éléments négatifs 3D Secure AVS NETBANX gère les vérifications d adresse (AVS) lorsque la banque émettrice prend cette caractéristique en charge. Le système AVS vérifie si l adresse fournie par le client qui se sert d une carte correspond à l adresse de facturation associée à cette carte par la banque émettrice. Il est plus difficile de se servir d une carte de manière frauduleuse puisque pour se servir d une carte volée, il faut aussi connaître l adresse de facturation associée à la carte. En outre, si les marchandises doivent être livrées, le marchand peut exiger qu elles le soient à l adresse de facturation associée à la carte. NETBANX configure chaque mode de paiement avec un ensemble acceptable de codes de retour AVS. Si la banque retourne un code qui n est pas acceptable compte tenu du mode de paiement, la requête est alors rejetée en renvoyant une erreur Échec d autorisation. Lorsqu une erreur Échec d autorisation est retournée en réponse à une requête de transaction et qu un numéro d autorisation est inclus dans la réponse, l échec a été causé par la vérification AVS. Vous pouvez consulter le code AVS retourné pour établir le motif exact pour lequel la vérification AVS a échoué. NETBANX retourne les codes suivants, dans l élément avsresponse, à l application du marchand en réponse à la requête de transaction ; les codes A, N et E indiquent un échec AVS : Tableau 1-5 : Codes AVS Lettre du code A B E M N Q Explication L adresse correspond, mais le code Zip ne correspond pas. La vérification AVS n a pas été faite pour la transaction internationale. Le format du code postal est invalide ou l'information relative à l'adresse n'a pas été fournie. Le système AVS ne prend pas cette industrie en charge. Correspondance de l adresse et du code postal pour les transactions internationales. Aucun élément de l adresse ne correspond. Réponse inconnue de l'émetteur/banknet switch. Guide de référence de l API pour les Services Web

12 Services Web de NETBANX juillet 2014 Tableau 1-5 : Codes AVS (suite) Lettre du code R S U W X Y Z Explication Réessayer. Le système est incapable de faire le traitement. L AVS n est pas pris en charge. L information sur l adresse n est pas disponible. Le code Zip de neuf chiffres correspond, mais l adresse ne correspond pas. Exact. Correspondance entre le code Zip de neuf chiffres et l adresse. Oui. Correspondance entre le code Zip de cinq chiffres et l adresse. Le code Zip de cinq chiffres correspond, mais l adresse ne correspond pas. Lorsque vous vous êtes inscrit à NETBANX, votre compte a été configuré pour faire des vérifications AVS automatiques. NETBANX n accepte les transactions que si les codes de retour AVS permis sont retournés. Il existe trois exceptions AVS, ce qui peut avoir un effet sur les décisions que vous prenez à l égard des vérifications AVS ayant échoué : Le système AVS n est pas toujours fiable. De faux résultats peuvent être retournés si la personne a déménagé, par exemple, ou parce que certaines personnes inscrivent des codes Zip à cinq chiffres tandis que d autres inscrivent des codes Zip à neuf chiffres. Le système AVS offre une prise en charge internationale limitée. Par conséquent, si vous décidez de n expédier qu aux adresses qui retournent de bons résultats AVS, vous pourriez exclure par ailleurs des transactions valides. Plusieurs banques émettrices aux États-Unis, mais pas toutes, prennent AVS en charge. Par conséquent, même si vous ne faites des affaires qu avec des clients américains, vous ne pourrez pas toujours vous fier à la disponibilité du système AVS. CVD La valeur CVD est un nombre à trois ou quatre chiffres imprimé sur la carte de crédit, mais qui n apparaît pas sur la bande magnétique. Par conséquent, la valeur n est pas imprimée sur les reçus ou les états de compte, ce qui réduit la possibilité de fraude en se servant de l information imprimée. La caractéristique CVD, conçue précisément pour les transactions où une carte n est pas utilisée, est une exigence de NETBANX. Nous prenons en charge la caractéristique CVD partout où les banques émettrices le font. Lorsqu un client saisit les renseignements relatifs à sa carte et au titulaire de la carte, la valeur CVD est demandée en même temps. Un indicateur parmi les quatre indicateurs suivants signale l état d une requête CVD : Not provided (non fournie) Le client n a pas fourni la valeur CVD. Provided (fournie) Le client a fourni la valeur CVD. Lorsque cet indicateur est choisi, la valeur CVD est fournie. Illegible (illisible) Le client prétend que la valeur CVD est illisible. Not present (absent) Le client prétend que la valeur CVD n apparaît pas sur la carte. 1-6

13 juillet 2014 Base de données des éléments négatifs Base de données des éléments négatifs 3D Secure NETBANX gère une base de données des éléments négatifs qui offre une protection supplémentaire contre la mauvaise utilisation des cartes et les requêtes de transaction inappropriées. Le numéro de la carte ou l'adresse de courriel est entré dans la base de données des éléments négatifs pour les motifs suivants : Une rétrofacturation liée au numéro de la carte ou à l adresse de courriel a été faite. Le numéro de la carte, ou l adresse de courriel, a été utilisé, ou vraisemblablement utilisé, dans le contexte d une activité frauduleuse. Votre compte est configuré pour la mise en œuvre automatique de cette caractéristique de sécurité et toutes les requêtes de transactions où on tente de se servir du numéro de la carte ou de l'adresse de courriel se trouvant dans la base de données des éléments négatifs ne seront pas traitées. NETBANX prend en charge 3D Secure, un programme d authentification des titulaires de cartes en ligne conçu pour rendre les transactions d achat sur Internet plus sécuritaires par la confirmation de l identité du titulaire au moment de l achat et avant que le marchand soumette la demande d autorisation. Le programme est actuellement compatible avec plusieurs types de cartes, notamment Visa (Vérifié par Visa), MasterCard (SecureCode) et JCB (J/Secure). Les autorisations traitées au moyen de 3D Secure sont garanties contre la plupart des types de litiges courants relativement à la rétrofacturation. Utilisation du présent guide Cible Le présent guide d utilisation décrit les fonctions importantes du système. Chaque section contient un aperçu des fonctions, lesquelles sont ensuite détaillées par procédures et selon la marche à suivre. Ce guide d utilisation s adresse aux marchands de NETBANX faisant usage de notre API des Services Web afin de traiter des demandes de transactions avec NETBANX. Fonctionnalités Symboles Il se peut que ce guide présente l explication de certaines caractéristiques auxquelles vous n avez pas accès. L accès auxdites fonctionnalités est octroyé aux marchands sur une base individuelle. Si vous avez des questions, communiquez avec votre gestionnaire de compte. Ce guide d utilisation fait appel aux symboles suivants pour mettre en évidence certains éléments importants : Guide de référence de l API pour les Services Web

14 Services Web de NETBANX juillet 2014 Tableau 1-6 : Symboles Symbole Description Cette icône remarque précède une astuce ou un conseil pour l utilisation de l application de traitement des transactions de manière plus efficace. Cette icône attention précède un avertissement relatif aux actions pouvant entraîner des conséquences importantes. 1-8

15 CHAPITRE 2 Transactions par prélèvement automatique (débit direct) Introduction Ce chapitre décrit comment traiter les transactions de prélèvement automatique à l aide du Service Web de NETBANX. Les opérations suivantes sont prises en charge : Tableau 2-1 : Opérations prises en charge Opération Description Pour Type de requête verify (vérification) Vous permet de confirmer que le compte bancaire d un client est en règle, sans toutefois retirer de l argent du compte. EFT ACH charge (facturation) credit (crédit) Vous permet de transférer des fonds du compte bancaire d un client vers votre compte de marchand. Cette transaction se fait en temps réel, bien que le réseau bancaire ne transfère les fonds que trois à cinq jours plus tard. Vous permet de transférer des fonds de votre compte de marchand directement au compte bancaire du client. Cette transaction se fait en temps réel, bien que le réseau bancaire ne transfère les fonds que trois à cinq jours plus tard. EFT ACH BACS SEPA* EFT ACH BACS SEPA Consultez la rubrique Bâtir des requêtes de facturation, de vérification ou de crédit à la page 2-4. updateshippinginfo Vous permet de transmettre l information d expédition, y compris le numéro de suivi, lorsque vous avez expédié la marchandise pour laquelle vous avez déjà traité une transaction de facturation. EFT ACH SEPA Consultez la rubrique Création de requêtes updateshippinginfo à la page lookuprequest Vous permet de produire un rapport à l aide de l API pour une plage de temps que vous précisez, afin de recevoir les données concernant les transactions de charge et de credit par prélèvement automatique qui sont traitées par votre compte de marchand. EFT ACH BACS SEPA Consultez la rubrique Création de lookuprequest (requêtes de consultation) à la page mandaterequest Vous permet de créer un mandat pour le compte bancaire d un client et de le déposer à sa banque, afin que vous puissiez transférer des fonds du compte bancaire du client vers votre compte commercial. Le réseau bancaire traite généralement le mandat en cinq jours. BACS SEPA Consultez la rubrique Création de mandaterequest pour BACS (requêtes de mandat) à la page Guide de référence de l API pour les Services Web

16 Transactions par prélèvement automatique (débit direct) juillet 2014 Tableau 2-1 : Opérations prises en charge Opération Description Pour Type de requête changestatusrequest Vous permet de changer l état d une transaction de facturation, de crédit ou de mandat. EFT ACH BACS SEPA Consultez la rubrique Création de changestatusrequest (requêtes de modification d état) à la page updatemandaterequest Vous permet de mettre à jour les informations contenues dans un mandat existant. SEPA Consultez la rubrique Création de updatemandaterequest (mise à jour du mandat) à la page *SEPA = espace unique de paiement en euros La disponibilité des types d opérations par prélèvement automatique est attribuée aux marchands sur une base individuelle, puisque ce ne sont pas toutes les banques des marchands qui acceptent toutes les opérations. Si vous avez des questions, communiquez avec votre gestionnaire de compte. Les transactions verify, charge et credit acceptent l objet de document ddcheckrequestv1. La transaction updateshippinginfo accepte l objet de document ddshippingrequestv1. La transaction lookup accepte l objet de document ddlookuprequestv1. La transaction mandat accepte l objet de document ddmandaterequestv1. La transaction changestatus accepte l objet de document ddchangestatusrequestv1. La transaction updatemandate accepte l objet de document ddupdatemandaterequestv1. Toutes les opérations retournent une réponse ddcheckresponsev1. Exemple.NET Pour bâtir l exemple pour.net : 1. Créez un nouveau projet. 2. Ajoutez une référence Web. 2-2

17 juillet 2014 Exemple.NET 3. Saisissez l URL WSDL et cliquez sur le bouton Ajouter une référence. Le client Web est maintenant créé. 4. Bâtissez la requête de prélèvement automatique et traitez la réponse. Consultez la rubrique Bâtir des requêtes de facturation, de vérification ou de crédit à la page 2-4. Consultez la rubrique Création de requêtes updateshippinginfo à la page Guide de référence de l API pour les Services Web

18 Transactions par prélèvement automatique (débit direct) juillet 2014 Consultez la rubrique Traitement de la réponse à la page Bâtir des requêtes de facturation, de vérification ou de crédit Les requêtes charge, verify et credit requièrent l objet de document ddcheckrequestv1. La présente rubrique décrit la structure d une requête ddcheckrequestv1 et la façon de la bâtir. Pour obtenir des détails sur les éléments requis, consultez le Tableau 2-2 : Éléments de transaction ddcheckrequestv1 à la page 2-7. Exemple de facturation C# Voici un exemple de transaction charge en C#. Pour convertir cette requête en requête credit ou verify, il suffit de remplacer la valeur «charge» (soulignée ci-dessous) par «credit» ou «verify» respectivement. // Prepare the call to the Direct Debit Web Service DDCheckRequestV1 ddcheckrequest = new DDCheckRequestV1(); ddcheckrequest.amount = "10.00"; MerchantAccountV1 merchantaccount = new MerchantAccountV1(); merchantaccount.accountnum = " "; merchantaccount.storeid = "mystoreid"; merchantaccount.storepwd = "mystorepwd"; ddcheckrequest.merchantaccount = merchantaccount; CheckV1 check = new CheckV1(); check.routingnum = " "; check.accountnum = " "; check.accounttype = BankAccountTypeV1.PC; check.bankname = "Chase"; check.checknum = 12; check.payee = "ACME Inc."; ddcheckrequest.check = check; BillingDetailsV1 billingdetails = new BillingDetailsV1(); billingdetails.firstname = "Jane"; billingdetails.lastname = "Jones"; billingdetails.street = "123 Main Street"; billingdetails.city = "LA"; billingdetails.country = CountryV1.US; billingdetails.zip = "90210"; billingdetails.phone = " "; billingdetails.checkpaymethod = CheckPayMethodV1.WEB; ddcheckrequest.billingdetails = billingdetails; //Perform the Web Services call to process the charge DirectDebitServiceV1 ddservice = new DirectDebitServiceV1(); DDCheckResponseV1 ddtxnresponse = ddservice.charge(ddcheckrequest); // Print out the result String responsetxt = ddtxnresponse.code + " - " + ddtxnresponse.decision + " - " + ddtxnresponse.description; responsetxt += "Details:" + Environment.NewLine; if (ddtxnresponse.detail!= null) { for (int i = 0; i < ddtxnresponse.detail.length; i++) { 2-4

19 juillet 2014 Exemple de facturation C# responsetxt += " - " + ddtxnresponse.detail[i].tag + " - " + ddtxnresponse.detail[i].value + Environment.NewLine; } } responsetxt = responsetxt.replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ddtxnresponse.decision); } Guide de référence de l API pour les Services Web

20 Transactions par prélèvement automatique (débit direct) juillet 2014 Diagramme de transaction ddcheckrequestv1 L objet de document ddcheckrequestv1 respecte la structure suivante : 2-6

21 juillet 2014 Éléments de transaction ddcheckrequestv1 Éléments de transaction ddcheckrequestv1 Ce type de requête est utilisé dans le cadre de divers plans de prélèvements automatiques. Consultez le Tableau 2-3 : Exigences supplémentaires pour les éléments de prélèvement automatique à la page 2-13 pour en savoir plus sur les différents éléments requis. L objet de document ddcheckrequestv1 peut contenir les éléments suivants : Tableau 2-2 : Éléments de transaction ddcheckrequestv1 Élément Élément enfant Requis Type Description merchantaccount accountnum Oui Chaîne Max = 10 storeid Oui Chaîne Max = 80 storepwd Oui Chaîne Max = 20 merchantrefnum Conditionnel Chaîne Max = 255 amount Oui Chaîne Max = Il s agit du numéro de compte de marchand. Il s agit de l identifiant du magasin traitant la transaction ; il sert à authentifier la requête. NETBANX le définit et le fournit au marchand comme élément du processus d intégration. Il s agit du mot de passe du magasin traitant la transaction ; il sert à authentifier la requête. NETBANX le définit et le fournit au marchand comme élément du processus d intégration. Il s agit d un numéro d identification (ID) unique, associé à chaque requête. La valeur est créée par le marchand et envoyée en tant qu élément de la requête. Il s agit du montant de la requête de transaction. check accounttype Oui Énumération Il s agit du type de compte chèque utilisé pour la transaction. Les valeurs possibles sont : PC (Compte chèque personnel) PS (Compte épargne personnel) PL (Compte prêt personnel) BC (Compte chèque commercial) BS (Compte épargne commercial) BL (Compte prêt commercial) bankname Oui Chaîne Max = 40 checknum Oui Long Max = 8 accountnum Oui Chaîne Max = 17 Si IBAN, Max = 32 Il s agit du nom de la banque du client, là où cette transaction est publiée. Il s agit du numéro de série du chèque fourni au moment de la requête de transaction. REMARQUE : L élément checknum est requis pour l opération verify où il sert de numéro d identification unique de la transaction même si aucune somme n est transférée entre les comptes durant cette opération. Il s agit du numéro du compte bancaire du client. Pour les transactions SEPA, il s agit du numéro IBAN (numéro de compte bancaire international) du client. Guide de référence de l API pour les Services Web

22 Transactions par prélèvement automatique (débit direct) juillet 2014 Tableau 2-2 : Éléments de transaction ddcheckrequestv1 (suite) Élément Élément enfant Requis Type Description routingnum Oui Chaîne Min = 6 Max = 9 Si BIC, Min = 8 Max = 11 payee Conditionnel Chaîne Max = 81 Pour les comptes en dollars américains, il s agit du numéro d acheminement à neuf chiffres de la banque du client. Pour les comptes en livres anglaises, il s agit du code de tri à six chiffres de la banque du client. Pour les comptes en dollars canadiens, ce numéro est composé de l'id de l'institution à trois chiffres suivi du numéro de transit à cinq chiffres de la succursale bancaire du client. Ils doivent être saisis dans cet ordre. N insérez pas d espaces ou de tirets. Pour les transactions SEPA, il s agit du code BIC (code identificateur de banque) du compte bancaire du client. Il s agit du descripteur qui apparaîtra sur le relevé bancaire du client. Il n est requis que pour les transactions credit et verify. Si vous entrez une valeur pour ce champ, celleci servira de descripteur sur le relevé. Si vous n entrez pas une valeur pour ce champ, une valeur par défaut, configurée pour le compte de marchand, servira de descripteur sur le relevé. bankcountry Conditionnel Énumération Il s agit du pays dans lequel la banque est située. Consultez la rubrique Codes de pays à la page C-3 pour connaître les bons codes à utiliser. Cet élément n est requis que pour certains pays. bankcity Conditionnel Chaîne Max = 40 mandatereference Conditionnel Chaîne Max = 10 Pour SEPA, Max = 35 Il s agit de la ville dans laquelle la banque est située. Cet élément n est requis que pour certains pays. Ceci est la référence du mandat permettant de porter les frais au compte bancaire. Cette valeur est retournée pour le paramètre mandatereference en réponse à la ddmandaterequestv1. Pour SEPA cet élément est requis. billingdetails checkpaymethod Oui Énumération Il s agit du type de paiement. Les valeurs possibles sont : WEB (compte chèque personnel seulement) TEL (compte chèque personnel seulement) PPD (compte chèque personnel seulement) CCD (compte chèque commercial seulement) firstname Conditionnel Chaîne Max = 40 lastname Conditionnel Chaîne Max = 40 Il s agit du prénom du client. Requis si checkpaymethod est réglé à WEB ou TEL. Il s agit du nom de famille du client. Requis si checkpaymethod est réglé à WEB ou TEL. 2-8

23 juillet 2014 Éléments de transaction ddcheckrequestv1 Tableau 2-2 : Éléments de transaction ddcheckrequestv1 (suite) Élément Élément enfant Requis Type Description companyname Conditionnel Chaîne Max = 50 street Oui Chaîne Max = 50 street2 Facultatif Chaîne Max = 50 city Oui Chaîne Max = 40 state/region Conditionnel Si state (État), alors Énumération Si region (région), alors chaîne Max = 40 Il s agit du nom de l entreprise. Requis si checkpaymethod est un chèque commercial. Il s agit de la première ligne de l adresse municipale du client. Il s agit de la deuxième ligne de l adresse municipale du client. Il s agit de la ville de résidence du client. Il s agit de l État, de la province ou de la région de résidence du client. Fournir la liste des États ou provinces pour les adresses à l intérieur des États-Unis ou du Canada. Fournir la liste des régions pour les adresses à l extérieur des États-Unis ou du Canada. Consultez la rubrique Annexe C : Codes géographiques pour connaître les bons codes à utiliser. country Oui Énumération Il s agit du pays de résidence du client. Consultez la rubrique Codes de pays à la page C-3 pour connaître les bons codes à utiliser. zip Facultatif Chaîne Max = 10 phone Oui Chaîne Max = 40 Facultatif Chaîne Max = 100 personalid idnumber Facultatif Chaîne Max = 20 Si le pays est États-Unis, il s'agit du code Zip du client ; sinon, il s'agit de son code postal. Il s agit du numéro de téléphone du client. Il s agit de l adresse de courriel du client. Il s agit du numéro de l ID fourni pour l élément idtype. idtype Facultatif Énumération Il s agit du type d ID utilisé pour identifier le propriétaire du compte bancaire. Les valeurs possibles sont : DL (permis de conduire) SS (ID gouvernemental) MI (ID militaire) GN (ID général) Guide de référence de l API pour les Services Web

24 Transactions par prélèvement automatique (débit direct) juillet 2014 Tableau 2-2 : Éléments de transaction ddcheckrequestv1 (suite) Élément Élément enfant Requis Type Description state/region Facultatif Si state (État), alors Énumération Si region (région), alors Chaîne Max = 40 country Facultatif Chaîne Longueur = 2 Il s agit de l État, de la province ou de la région qui a émis l ID. Fournir la liste des États ou provinces pour les adresses à l intérieur des États-Unis ou du Canada. Fournir la liste des régions pour les adresses à l extérieur des États-Unis ou du Canada. Consultez la rubrique Annexe C : Codes géographiques pour connaître les bons codes à utiliser. Il s agit du pays d émission de l ID. Les valeurs possibles sont : CA (Canada) US (États-Unis) expiry Facultatif L élément enfant expiry a trois autres éléments enfants. Élément enfant de expiry day Facultatif Entier Longueur = 2 month Facultatif Entier Longueur = 2 year Conditionnel Entier Longueur = 4 socialsecuritynumber Facultatif Chaîne Max = 12 Il s agit du jour d expiration de l ID. Il s agit du mois d expiration de l ID. Il s agit de l année d expiration de l ID. Cet élément est requis si l élément expiry est inclus. Il s agit du numéro d assurance sociale du client. dateofbirth Facultatif Il s agit de la date de naissance du client. year Conditionnel Chaîne Max = month Conditionnel Chaîne Max = 12 day Conditionnel Chaîne Max = 31 Il s agit de l année de naissance du client. Il s agit du mois de naissance du client. Il s agit du jour de naissance du client. shippingdetails carrier Facultatif Énumération Il s agit du transporteur de l envoi. Les valeurs possibles sont : APC = APC Overnight APS = AnPost CAD = Service postal du Canada DHL FEX = FedEx RML = Royal Mail UPS = United Parcel Service USPS = United States Postal Service OTHER = Autre 2-10

25 juillet 2014 Éléments de transaction ddcheckrequestv1 Tableau 2-2 : Éléments de transaction ddcheckrequestv1 (suite) Élément Élément enfant Requis Type Description trackingnumber Facultatif Chaîne Max = 50 Il s agit du numéro de suivi d expédition fourni par le transporteur. shipmethod Facultatif Énumération Il s agit du mode d expédition. Les valeurs possibles sont : N = Jour suivant/de nuit T = Deux jours C = Coût le plus bas O = Autre firstname Facultatif Chaîne Max = 40 lastname Facultatif Chaîne Max = 40 street Facultatif Chaîne Max = 50 street2 Facultatif Chaîne Max = 50 city Facultatif Chaîne Max = 40 state/region Facultatif Si state (État), alors Énumération Si region (région), alors Chaîne Max = 40 Il s agit du prénom du destinataire. Il s agit du nom de famille du destinataire. Il s agit de la première ligne de l adresse municipale du destinataire. Il s agit de la deuxième ligne de l adresse municipale du destinataire. Il s agit de la ville de résidence du destinataire. Il s agit de l État, de la province ou de la région de résidence du destinataire. Fournir la liste des États ou provinces pour les adresses à l intérieur des États-Unis ou du Canada. Consultez la rubrique Annexe C : Codes géographiques pour connaître les bons codes à utiliser. country Facultatif Énumération Il s agit du pays de résidence du destinataire. Consultez la rubrique Codes de pays à la page C-3 pour connaître les bons codes à utiliser. zip Facultatif Chaîne Max = 10 phone Facultatif Chaîne Max = 40 Facultatif Chaîne Max = 100 customerip Facultatif Chaîne Max = 50 Si le pays est États-Unis, il s'agit du code Zip du destinataire ; sinon, il s'agit de son code postal. Il s agit du numéro de téléphone du destinataire. Il s agit de l adresse de courriel du destinataire. Il s agit de l adresse IP du client. Guide de référence de l API pour les Services Web

26 Transactions par prélèvement automatique (débit direct) juillet 2014 Tableau 2-2 : Éléments de transaction ddcheckrequestv1 (suite) Élément Élément enfant Requis Type Description producttype Facultatif Énumération Il s agit du type de produit vendu. Les valeurs possibles sont : P(Biens matériels) D(Produits numériques) C (Contenu numérisé) G (Bon-cadeau ou argent électronique) S (Logiciel contributif) M (Numérique et Matériel) R (Réapprovisionnement de compte) txnappliedto Non Cet élément ne s applique pas aux transactions par prélèvement automatique. confirmationnumber Conditionnel Chaîne Max = 20 Il s agit du numéro de confirmation retourné par NETBANX en réponse à la requête initiale charge. N incluez cet élément que si vous utilisez ddcheckrequestv1 pour traiter une requête credit. targetvirtualaccount Non Cet élément ne s applique pas aux transactions par prélèvement automatique. checkriskservice Non Cet élément ne s applique pas aux transactions par prélèvement automatique. txndate Facultatif datetime Il s agit de la date et de l heure auxquelles la transaction a eu lieu. Pour les charge, credit, ou mandaterequest, cette valeur peut indiquer la date et l heure à laquelle la transaction aura lieu. Pour les transactions SEPA, cette valeur indique la prochaine date de paiement. Celle-ci est obligatoire et doit accorder un délai d au moins six jours ouvrables pour les First (premières) transactions ou les transactions One-Off (uniques), et d au moins trois jours ouvrables pour les transactions Recurring (récurrentes) ou les Final (finales) transactions. REMARQUE : La date de paiement sera retournée dans la paire tag/value, dans l élément detail de la réponse (consultez le Tableau 2-10 : Éléments de réponse ddcheckresponsev1 à la page 2-36). sdk version Conditionnel Chaîne Max = 20 platform Conditionnel Chaîne Max = 10 Il s agit de la version de SDK utilisée, le cas échéant. Requis si l élément sdk est fourni. Il s agit de la langue d intégration de SDK utilisée (par ex., Java,.NET). Requis si l élément sdk est fourni. 2-12

27 juillet 2014 Éléments de transaction ddcheckrequestv1 Tableau 2-2 : Éléments de transaction ddcheckrequestv1 (suite) Élément Élément enfant Requis Type Description provider Conditionnel Chaîne Max = 20 Il s agit de l auteur de SDK utilisé. Réglez cette valeur à «op» lorsque le SDK est fourni par NETBANX. Requis si l élément sdk est fourni. origin Facultatif Énumération Il s'agit de l origine de la requête. Les valeurs possibles sont : Sans fil Réseau filaire addendumdata tag Facultatif Chaîne Max = 30 value Facultatif Chaîne Max = 1024 Il s agit de données supplémentaires que le marchand peut inclure dans la requête de transaction. Il s agit de données supplémentaires que le marchand peut inclure dans la requête de transaction. Considérations spéciales relatives aux éléments de prélèvement automatique Certains marchands sont intégrés à des processeurs ayant des exigences concernant certains éléments obligatoires. Si tel est le cas, les règles suivantes s appliquent: Tableau 2-3 : Exigences supplémentaires pour les éléments de prélèvement automatique Élément Transactions réguliers Transactions garanties Transactions SEPA check.accounttype Requis Requis Facultatif check.bankname Requis Requis Facultatif check.checknum Requis Requis Facultatif check.payee Facultatif Facultatif Requis check.bankcountry Conditionnel Conditionnel Facultatif check.bankcity Conditionnel Conditionnel Facultatif check.mandatereference Conditionnel Conditionnel Requis billingdetails.firstname Conditionnel Requis Requis billingdetails.lastname Conditionnel Requis Requis billingdetails.companyname Conditionnel Conditionnel Facultatif billingdetails.state Conditionnel Requis Facultatif billingdetails.zip Facultatif Requis Requis billingdetails.phone Facultatif Requis Facultatif billingdetails. Facultatif Requis Requis customerip Facultatif Requis Facultatif dateofbirth.year Facultatif Requis Facultatif dateofbirth.month Facultatif Requis Facultatif Guide de référence de l API pour les Services Web

28 Transactions par prélèvement automatique (débit direct) juillet 2014 Tableau 2-3 : Exigences supplémentaires pour les éléments de prélèvement automatique (suite) Élément Transactions réguliers Transactions garanties Transactions SEPA dateofbirth.day Facultatif Requis Facultatif personalid.idnumber Facultatif Requis Facultatif personalid.state Facultatif Requis Facultatif socialsecuritynumber Facultatif Requis Facultatif txndate Facultatif Facultatif Requis Votre gestionnaire de compte vous informera si vous êtes intégré à ce type de processeur et si vous êtes admissible au traitement par prélèvement automatique garantie. Création de requêtes updateshippinginfo Tous les éléments facultatifs qui requièrent des types de données non nullables (ordinaires) (par ex., int ou enum) doivent avoir leur attribut specified établi à true lorsque les valeurs sont fixées pour ces éléments. Consultez l élément shipmethod dans l exemple ci-dessous. La transaction updateshippinginfo requiert l objet de document ddshippingrequestv1. La présente rubrique décrit la structure d une requête ddshippingrequestv1 et la façon de la bâtir. Pour obtenir des détails sur les éléments requis, consultez le Tableau 2-4 : Éléments de transaction ddshippingrequestv1 à la page Exemple de transaction updateshippinginfo C# Voici un exemple de transaction updateshippinginfo en C#. // Prepare the call to the Direct Debit Web Service DDShippingRequestV1 ddshippingrequest = new DDShippingRequestV1(); MerchantAccountV1 merchantaccount = new MerchantAccountV1(); merchantaccount.accountnum = " "; merchantaccount.storeid = "mystoreid"; merchantaccount.storepwd = "mystorepwd"; ddshippingrequest.merchantaccount = merchantaccount; ddshippingrequest.confirmationnumber = "123456"; // A valid confirmation number from a previous settle auth or purchase ddshippingrequest.carrier = CarrierV1.FEX; // Fedex ddshippingrequest.shipmethod = ShipMethodV1.T; ddshippingrequest.shipmethodspecified = true; ddshippingrequest.trackingnumber = " "; ddshippingrequest.firstname = "Jeanne"; ddshippingrequest.lastname = "Tremblay"; ddshippingrequest.street = "123 rue Principale"; ddshippingrequest.city = "Alma"; ddshippingrequest.country = CountryV1.CA; ddshippingrequest.countryspecified = true; ddshippingrequest.zip = "G0W 1G0"; ddshippingrequest. = "jeannetremblay@ server.com"; //Perform the Web Services call to update the shipping info 2-14

29 juillet 2014 Exemple de transaction updateshippinginfo C# DirectDebitServiceV1 ddservice = new DirectDebitServiceV1(); DDCheckResponseV1 ddtxnresponse = ddservice.updateshippinginfo(ddshippingrequest); // Print out the result String responsetxt = ddtxnresponse.code + " - " + ddtxnresponse.decision + " - " + ddtxnresponse.description; responsetxt += "Details:" + Environment.NewLine; if (ddtxnresponse.detail!= null) { for (int i = 0; i < ddtxnresponse.detail.length; i++) { responsetxt += " - " + ddtxnresponse.detail[i].tag + " - " + ddtxnresponse.detail[i].value + Environment.NewLine; } } responsetxt = responsetxt.replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ddtxnresponse.decision); } Guide de référence de l API pour les Services Web

30 Transactions par prélèvement automatique (débit direct) juillet 2014 Diagramme de transaction ddshippingrequestv1 L objet de document ddshippingrequestv1 respecte la structure suivante : 2-16

31 juillet 2014 Éléments de transaction ddshippingrequestv1 Éléments de transaction ddshippingrequestv1 L objet de document ddshippingrequestv1 peut contenir les éléments suivants : Tableau 2-4 : Éléments de transaction ddshippingrequestv1 Élément Élément enfant Requis Type Description merchantaccount accountnum Oui Chaîne Max = 10 storeid Oui Chaîne Max = 80 storepwd Oui Chaîne Max = 20 Il s agit du numéro de compte de marchand. Il s agit de l identifiant du magasin traitant la transaction ; il sert à authentifier la requête. NETBANX le définit et le fournit au marchand comme élément du processus d intégration. Il s agit du mot de passe du magasin traitant la transaction ; il sert à authentifier la requête. NETBANX le définit et le fournit au marchand comme élément du processus d intégration. carrier Oui Énumération Il s agit du transporteur de l envoi. Les valeurs possibles sont : APC = APC Overnight APS = AnPost CAD = Service postal du Canada DHL FEX = FedEx RML = Royal Mail UPS = United Parcel Service USPS = United States Postal Service AUTRE trackingnumber Oui Chaîne Max = 50 confirmationnumber Oui Chaîne Max = 20 Il s agit du numéro de suivi d expédition fourni par le transporteur. Il s agit du numéro de confirmation retourné par NETBANX. shipmethod Facultatif Énumération Il s agit du mode d expédition. Les valeurs possibles sont : N = Jour suivant/de nuit T = Deux jours C = Coût le plus bas O = Autre firstname Facultatif Chaîne Max = 40 lastname Facultatif Chaîne Max = 40 street Facultatif Chaîne Max = 50 street2 Facultatif Chaîne Max = 50 Il s agit du prénom du client. Il s agit du nom de famille du client. Il s agit de la première ligne de l adresse municipale du client. Il s agit de la deuxième ligne de l adresse municipale du client. Guide de référence de l API pour les Services Web

32 Transactions par prélèvement automatique (débit direct) juillet 2014 Tableau 2-4 : Éléments de transaction ddshippingrequestv1 (suite) Élément Élément enfant Requis Type Description city Facultatif Chaîne Max = 40 state/region Facultatif Si state (État), alors Énumération Si region (région), alors Chaîne Max = 40 Il s agit de la ville de résidence du client. Il s agit de l État, de la province ou de la région de résidence du client. Fournir la liste des États ou provinces pour les adresses à l intérieur des États-Unis ou du Canada. Fournir la liste des régions pour les adresses à l extérieur des États-Unis ou du Canada. Consultez la rubrique Annexe C : Codes géographiques pour connaître les bons codes à utiliser. country Facultatif Énumération Il s agit du pays de résidence du client. Consultez la rubrique Codes de pays à la page C-3 pour connaître les bons codes à utiliser. zip Facultatif Chaîne Max = 10 phone Facultatif Chaîne Max = 40 Facultatif Chaîne Max = 100 Si le pays est États-Unis, il s'agit du code Zip du client ; sinon, il s'agit de son code postal. Il s agit du numéro de téléphone du client. Il s agit de l adresse de courriel du client. Création de lookuprequest (requêtes de consultation) La requête de consultation du prélèvement automatique vous permet de produire un rapport à l aide de l API pour une plage de temps que vous précisez, afin de recevoir les données concernant les transactions de facturation et de crédit par prélèvement automatique qui sont traitées par votre compte de marchand. Exemple de transaction lookuprequest C# Voici un exemple de transaction ddlookuprequest en C#. // Prepare the call to the Direct Debit Web Service DDLookupRequestV1 ddlookuprequest = new DDLookupRequestV1(); MerchantAccountV1 merchantaccount = new MerchantAccountV1(); merchantaccount.accountnum = " "; merchantaccount.storeid = "mystoreid"; merchantaccount.storepwd = "mystorepwd"; ddlookuprequest.merchantaccount = merchantaccount; ddlookuprequest.confirmationnumber = " "; DateV1 startdate = new DateV1(); startdate.year = "2012"; startdate.month = "08"; startdate.day = "15"; startdate.hour = "11"; 2-18

33 juillet 2014 Exemple de transaction lookuprequest C# startdate.minute = "00"; startdate.second = "00"; ddlookuprequest.startdate = startdate; ddlookuprequest.startdatespecified = true; DateV1 enddate = new DateV1(); enddate.year = "2012"; enddate.month = "08"; enddate.day = "15"; enddate.hour = "14"; enddate.minute = "00"; enddate.second = "00"; ddlookuprequest.enddate = enddate; ddlookuprequest.enddatespecified = true; //Perform the Web Services call to process the charge DirectDebitServiceV1 ddservice = new DirectDebitServiceV1(); DDCheckResponseV1 ddcheckresponse = ddservice.lookup(ddlookuprequest); // Print out the result String responsetxt = ddcheckresponse.code + " - " + ddcheckresponse.decision; responsetxt += "Transactions:" + Environment.NewLine; if (ddcheckresponse.transaction!= null) { for (int i = 0; i < ddcheckresponse.transaction.length; i++) { responsetxt += " - confirmationnumber: " + ddcheckresponse.transaction[i].confirmationnumber + Environment.NewLine; responsetxt += " - merchantrefnum: " + ddcheckresponse.transaction[i].merchantrefnum + Environment.NewLine; responsetxt += " - txntime: " + ddcheckresponse.transaction[i].txntime + Environment.NewLine; responsetxt += " - amount: " + ddcheckresponse.transaction[i].amount + Environment.NewLine; StatusV1 status = ddcheckresponse.transaction[i].status; if (status!= null){ responsetxt += " - status: " + status.code + Environment.NewLine; responsetxt += " - status effective date:" + status.effectivedate + Environment.NewLine; } responsetxt += Environment.NewLine; } } responsetxt = responsetxt.replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ddCheckResponse.decision)) { System.Console.WriteLine("Transaction Found."); } else { System.Console.WriteLine("Transaction Failed or Not Found with decision: " + ddcheckresponse.decision); } Guide de référence de l API pour les Services Web

34 Transactions par prélèvement automatique (débit direct) juillet 2014 Diagramme de transaction ddlookuprequestv1 L objet de document ddlookuprequestv1 respecte la structure suivante : Éléments de transaction ddlookuprequestv1 L objet de document ddlookuprequestv1 peut contenir les éléments suivants : Tableau 2-5 : Éléments de transaction ddlookuprequestv1 Élément Élément enfant Requis Type Description merchantaccount accountnum Oui Chaîne Max = 10 storeid Oui Chaîne Max = 80 Il s agit du numéro de compte de marchand. Il s agit de l identifiant du magasin traitant la transaction ; il sert à authentifier la requête. NETBANX le définit et le fournit au marchand comme élément du processus d intégration. 2-20

35 juillet 2014 Éléments de transaction ddlookuprequestv1 Tableau 2-5 : Éléments de transaction ddlookuprequestv1 (suite) Élément Élément enfant Requis Type Description storepwd Oui Chaîne Max = 20 confirmationnumber Facultatif Chaîne Max = 20 merchantrefnum Conditionnel Chaîne Max = 255 startdate year Oui Int Max = 9999 month Oui Int Min = 1 Max = 12 day Oui Int Min = 1 Max = 31 hour Oui Int Min = 0 Max = 23 minute Oui Int Min = 0 Max = 59 second Oui Int Min = 0 Max = 59 enddate year Oui Int Max = 9999 month Oui Int Min = 1 Max = 12 day Oui Int Min = 1 Max = 31 Il s agit du mot de passe du magasin traitant la transaction ; il sert à authentifier la requête. NETBANX le définit et le fournit au marchand comme élément du processus d intégration. Il s agit du numéro de confirmation retourné par NETBANX en réponse à la requête initiale. N incluez cet élément que si vous voulez effectuer une recherche à l aide de ce champ. Ce champ a préséance sur le champ merchantrefnum. Il s agit d un numéro d identification (ID) unique, associé à chaque requête. La valeur est créée par le marchand et envoyée en tant qu élément de la requête. Il s agit de l année fixée pour le début de la recherche. Il s agit du mois fixé pour le début de la recherche. Il s agit du jour fixé pour le début de la recherche. Il s agit de l heure fixée pour le début de la recherche. Il s agit de la minute fixée pour le début de la recherche. Il s agit de la seconde fixée pour le début de la recherche. Il s agit de l année fixée pour la fin de la recherche. Il s agit du mois fixé pour la fin de la recherche. Il s agit du jour fixé pour la fin de la recherche. Guide de référence de l API pour les Services Web

36 Transactions par prélèvement automatique (débit direct) juillet 2014 Tableau 2-5 : Éléments de transaction ddlookuprequestv1 (suite) Élément Élément enfant Requis Type Description hour Oui Int Min = 0 Max = 23 minute Oui Int Min = 0 Max = 59 second Oui Int Min = 0 Max = 59 Il s agit de l heure fixée pour la fin de la recherche. Il s agit de la minute fixée pour la fin de la recherche. Il s agit de la seconde fixée pour la fin de la recherche. Création de mandaterequest pour BACS (requêtes de mandat) La demande de mandat de prélèvements automatiques vous permet de créer un mandat pour le compte bancaire d un client et de le déposer à sa banque, afin que vous puissiez transférer des fonds du compte bancaire du client vers votre compte commercial. Lorsque vous soumettez une ddmandaterequestv1, NETBANX retournera une valeur pour le paramètre confirmationnumber dans la réponse. Il s agit de la valeur entrée dans la requête ou une valeur générée automatiquement par le système NETBANX. Vous aurez besoin de cette valeur dans l élément mandatereference (qui est un élément enfant de l élément check) lorsque vous traiterez des demandes de facturation à l aide de la ddcheckrequestv1. La valeur mandatereference doit contenir dix caractères. Si vous entrez une valeur de moins de dix caractères, le système NETBANX insérera des chiffres 0 avant celle-ci jusqu à ce qu elle compte 10 caractères. Par exemple, la valeur ABCDEFG deviendra 000ABCDEFG. Si vous n entrez aucune valeur, le système NETBANX en générera une et la retournera dans la réponse. Initialement, l état du mandat est réglé à W (En attente). Lorsque ce dernier est mis en lot, l état passe à C (Lot complet). À ce stade, le mandat ne peut pas être utilisé pour effectuer des prélèvements automatiques. Le réseau bancaire traite généralement le mandat en cinq jours. Après ce délai, et une fois le mandat mis en lot, NETBANX fait passer l état du mandat à AP (Mandat approuvé). Le mandat peut alors être utilisé pour autoriser des prélèvements automatiques dans le compte bancaire à l intention duquel il a été créé. Si la facture est postdatée en définissant la valeur txndate dans la requête ddcheckrequestv1, le mandat peut être utilisé même s il n est pas activé, dans la mesure où la valeur txndate a été définie de façon à fixer un délai d au moins cinq jours ouvrables, le temps que le mandat devienne actif. Afin de faciliter ce processus, la date d activation du mandat est indiquée dans l élément effectivedate en réponse à la requête ddmandaterequestv1. Les mandats sont automatiquement mis en lot le jour ouvrable suivant, sauf si la valeur autosend n est pas réglée à Y, auquel cas le mandat demeurera à l état PCA (Approbation du client en attente). Cet état intermédiaire et facultatif, antérieur à l état W, vous donne l occasion d effectuer d autres vérifications relatives au client, ou encore permet au client de vérifier l information reçue par mandatereference avant de continuer. Vous pouvez ensuite faire passer l état du mandat de PCA à W en effectuant une requête changestatus ou en utilisant le module d administration du marchand de NETBANX. 2-22

37 juillet 2014 Création de mandaterequest pour SEPA (requêtes de mandat) Création de mandaterequest pour SEPA (requêtes de mandat) Avant d effectuer un prélèvement automatique SEPA, vous devez préalablement avoir établi une entente de mandat avec votre client et indiquer l ID de référence du mandat dans l élément mandatereference. L ID de référence du mandat peut contenir jusqu à 35 caractères. Les mandats de prélèvements automatiques SEPA sont activés dès qu ils sont créés par le marchand. Après avoir envoyé une requête ddmandaterequest, vous pouvez donc immédiatement envoyer une requête ddcheckrequest. Pour en savoir plus consultez le SEPA Direct Debit Merchant Implementation Guide (en anglais), qui contient plus d information sur la logique métier et les processus associés au prélèvement automatique SEPA. Exemple de transaction mandaterequest C# Voici un exemple de transaction ddmandaterequest en C#. // Prepare the call to the Direct Debit Web Service DDMandateRequestV1 ddmandaterequest = new DDMandateRequestV1(); MerchantAccountV1 merchantaccount = new MerchantAccountV1(); merchantaccount.accountnum = " "; merchantaccount.storeid = "mystoreid"; merchantaccount.storepwd = "mystorepwd"; ddcheckrequest.merchantaccount = merchantaccount; CheckV1 check = new CheckV1(); check.routingnum = " "; check.accountnum = " "; check.bankname = "Chase"; check.payee = "ACME Inc."; ddmandaterequest.check = check; BillingDetailsV1 billingdetails = new BillingDetailsV1(); billingdetails.firstname = "Jeanne"; billingdetails.lastname = "Tremblay"; billingdetails.street = "123 rue Principale"; billingdetails.city = "Alma"; billingdetails.country = CountryV1.CA; billingdetails.zip = "G0W 1G0"; billingdetails.phone = " "; billingdetails.checkpaymethod = CheckPayMethodV1.WEB; ddmandaterequest.billingdetails = billingdetails; ddmandaterequest.autosend = "Y"; //Perform the Web Services call to process the charge DirectDebitServiceV1 ddservice = new DirectDebitServiceV1(); DDCheckResponseV1 ddtxnresponse = ddservice.mandate(ddcheckrequest); // Print out the result String responsetxt = ddtxnresponse.code + " - " + ddtxnresponse.decision + " - " + ddtxnresponse.description; responsetxt += "Details:" + Environment.NewLine; if (ddtxnresponse.detail!= null) { for (int i = 0; i < ddtxnresponse.detail.length; i++) { responsetxt += " - " + ddtxnresponse.detail[i].tag + " - " + ddtxnresponse.detail[i].value + Environment.NewLine; } } responsetxt = responsetxt.replace("\n", Environment.NewLine); Guide de référence de l API pour les Services Web

38 Transactions par prélèvement automatique (débit direct) juillet 2014 System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ddtxnresponse.decision); } 2-24

39 juillet 2014 Diagramme de transaction ddmandaterequestv1 Diagramme de transaction ddmandaterequestv1 L objet de document ddmandaterequestv1 respecte la structure suivante : Guide de référence de l API pour les Services Web

40 Transactions par prélèvement automatique (débit direct) juillet 2014 Éléments de transaction ddmandaterequestv1 L objet de document ddmandaterequestv1 peut contenir les éléments suivants : Table 2-6: Éléments de transaction ddmandaterequestv1 Element Child Element Required Type Description merchantaccount accountnum Oui Chaîne Max = 10 storeid Oui Chaîne Max = 80 storepwd Oui Chaîne Max = 20 merchantrefnum Conditionnel Chaîne Max = 255 Il s agit du numéro de compte de marchand. Il s agit de l identifiant du magasin traitant la transaction ; il sert à authentifier la requête. NETBANX le définit et le fournit au marchand comme élément du processus d intégration. Il s agit du mot de passe du magasin traitant la transaction ; il sert à authentifier la requête. NETBANX le définit et le fournit au marchand comme élément du processus d intégration. Il s agit d un numéro d identification (ID) unique, associé à chaque requête. La valeur est créée par le marchand et envoyée en tant qu élément de la requête. check accounttype Oui Énumération Il s agit du type de compte chèque utilisé pour la transaction. Les valeurs possibles sont : PC (Compte chèque personnel) PS (Compte épargne personnel) PL (Compte prêt personnel) BC (Compte chèque commercial) BS (Compte épargne commercial) BL (Compte prêt commercial) bankname Oui Chaîne Max = 40 checknum Oui Long Max = 8 accountnum Oui Chaîne Max = 17 routingnum Oui Chaîne Min = 6 Max = 9 Il s agit du nom de la banque du client, là où cette transaction est publiée. Il s agit du numéro de série du chèque fourni au moment de la requête de transaction. Il s agit du numéro du compte bancaire du client. Pour les transactions SEPA, il s agit du numéro IBAN (numéro de compte bancaire international) du client. Pour les comptes en livres anglaises, il s agit du code de tri à six chiffres de la banque du client. Pour les transactions SEPA, il s agit du code BIC (code identificateur de banque) du compte bancaire du client. 2-26

41 juillet 2014 Éléments de transaction ddmandaterequestv1 Table 2-6: Éléments de transaction ddmandaterequestv1 (suite) Element Child Element Required Type Description payee Facultatif Chaîne Max = 81 Il s agit du descripteur qui apparaîtra sur le relevé bancaire du client. Il n est requis que pour les transactions credit et verify. Si vous entrez une valeur pour ce champ, celle-ci servira de descripteur sur le relevé. Si vous n entrez pas une valeur pour ce champ, une valeur par défaut, configurée pour le compte de marchand, servira de descripteur sur le relevé. bankcountry Conditionnel Énumération Il s agit du pays dans lequel la banque est située. Consultez la rubrique Codes de pays à la page C-3 pour connaître les bons codes à utiliser. Cet élément n est requis que pour certains pays. bankcity Conditionnel Chaîne Max = 40 mandatereference Facultatif Chaîne Max = 10 Il s agit de la ville dans laquelle la banque est située. Cet élément n est requis que pour certains pays. Il s agit de la référence du mandat permettant de porter les frais au compte. Vous pouvez définir vous-même la valeur mandatereference lorsque vous effectuez la requête. Si vous n entrez aucune valeur dans ce champ, le système NETBANX en générera une et la retournera dans la réponse. Pour les transactions SEPA, cet élément est obligatoire. Le marchand doit créer sa propre valeur mandatereference. billingdetails checkpaymethod Facultatif Énumération Il s agit du type de paiement. Les valeurs possibles sont : WEB (compte chèque personnel seulement) TEL (compte chèque personnel seulement) PPD (compte chèque personnel seulement) CCD (compte chèque commercial seulement) firstname Conditionnel Chaîne Max = 40 lastname Conditionnel Chaîne Max = 40 companyname Conditionnel Chaîne Max = 50 Il s agit du prénom du client. Requis si checkpaymethod est réglé à WEB ou TEL. Il s agit du nom de famille du client. Requis si checkpaymethod est réglé à WEB ou TEL. Il s agit du nom de l entreprise. Requis si checkpaymethod est un chèque commercial. Guide de référence de l API pour les Services Web

42 Transactions par prélèvement automatique (débit direct) juillet 2014 Table 2-6: Éléments de transaction ddmandaterequestv1 (suite) Element Child Element Required Type Description street Facultatif Chaîne Max = 50 street2 Facultatif Chaîne Max = 50 city Facultatif Chaîne Max = 40 state/region Conditionnel Si state (État), alors Énumération Si region (région), alors chaîne Max = 40 Il s agit de la première ligne de l adresse municipale du client. Il s agit de la deuxième ligne de l adresse municipale du client. Il s agit de la ville de résidence du client. Il s agit de l État, de la province ou de la région de résidence du client. Fournir la liste des États ou provinces pour les adresses à l intérieur des États-Unis ou du Canada. Fournir la liste des régions pour les adresses à l extérieur des États-Unis ou du Canada. Consultez la rubrique Annexe C : Codes géographiques pour connaître les bons codes à utiliser. country Facultatif Énumération Il s agit du pays de résidence du client. Consultez la rubrique Codes de pays à la page C-3 pour connaître les bons codes à utiliser. zip Facultatif Chaîne Max = 10 phone Facultatif Chaîne Max = 40 Facultatif Chaîne Max = 100 customerip Facultatif Chaîne Max = 50 Si le pays est États-Unis, il s'agit du code Zip du client ; sinon, il s'agit de son code postal. Il s agit du numéro de téléphone du client. Il s agit de l adresse de courriel du client. Il s agit de l adresse IP du client. txndate Facultatif datetime Il s agit de la date et de l heure auxquelles la transaction a eu lieu. Pour les charge, credit, ou mandaterequest, cette valeur peut indiquer la date et l heure à laquelle la transaction aura lieu. 2-28

43 juillet 2014 Création de changestatusrequest (requêtes de modification d état) Table 2-6: Éléments de transaction ddmandaterequestv1 (suite) Element Child Element Required Type Description autosend Facultatif Booléen Ceci détermine le moment où le mandat sera envoyé à la banque. Les valeurs possibles sont : Y = Oui L état du mandat sera réglé à W (En attente), prêt à être envoyé à la banque. N = Non L état du mandat restera réglé à PCA (Approbation client en attente), et ce dernier ne sera pas envoyé à la banque. Si l état autosend est réglé à N, le mandat peut par la suite être changé pour W à l aide de la demande de changestatus. Le mandat sera alors acheminé à la banque lors du prochain envoi (consultez la rubrique Création de changestatusrequest (requêtes de modification d état) à la page 2-29). REMARQUE : Pour les transactions SEPA, cette valeur doit être réglée à Y. L état du mandat sera AP (Mandat approuvé). addendumdata tag Facultatif Chaîne Max = 30 value Facultatif Chaîne Max = 1024 Il s agit de données supplémentaires que le marchand peut inclure dans la requête de transaction. Il s agit de données supplémentaires que le marchand peut inclure dans la requête de transaction. Création de changestatusrequest (requêtes de modification d état) Une demande de modification d état vous permet de modifier l état de certains prélèvements automatiques. Vous pouvez apporter les modifications suivantes : Tableau 2-7 : Modification d état Solution Type de requête État initial État obtenu Prélèvement automatique au Royaume-Uni (BACS) mandaterequest (mandat) PCA Approbation du client en attente W En attente X Annulée Prélèvement automatique au Royaume-Uni (BACS) charge (facturation) credit (crédit) mandaterequest (mandat) W En attente X Annulée Guide de référence de l API pour les Services Web

44 Transactions par prélèvement automatique (débit direct) juillet 2014 Tableau 2-7 : Modification d état (suite) Solution Type de requête État initial État obtenu Prélèvement automatique au Royaume-Uni (marchands passerelle) charge (facturation) credit (crédit) mandaterequest (mandat) C Lot complet CL Transaction traitée RE Retournée REMARQUE : Utiliser seulement lorsque votre banque rejette la transaction et lorsque vous n avez pas obtenu de rapport BACS. Comptez 5 jours ouvrables après la fin de la transaction, puis communiquez avec le soutien technique avant d effectuer la demande de modification. EFT (TEF)/ACH (CCA) charge (facturation) credit (crédit) C Lot complet X Annulée REMARQUE : Possible seulement si la requête n a pas encore été envoyée à la banque. Prélèvement automatique SEPA mandaterequest (mandat) AP Active X Annulée Prélèvement automatique SEPA charge (facturation) W En attente C Lot complet X Annulée REMARQUE : Possible seulement jusqu à 5 jours après la compensation du prélèvement. NETBANX répond à votre demande de modification d état par une ddcheckresponsev1. Dans cette réponse, le confirmationnumber indique quelle demande a été mise à jour (charge, credit, ou mandaterequest), et vous permet de confirmer le nouvel état de la transaction que vous avez mise à jour. Pour obtenir plus de détails, consultez la rubrique Traitement de la réponse à la page Exemple de transaction changestatusrequest C# Voici un exemple de transaction ddchangestatusrequest en C#. // Prepare the call to the Direct Debit Web Service DDChangeStatusRequestV1 ddchangestatusrequest = new DDChangeStatusRequestV1(); MerchantAccountV1 merchantaccount = new MerchantAccountV1(); merchantaccount.accountnum = " "; merchantaccount.storeid = "mystoreid"; merchantaccount.storepwd = "mystorepwd"; ddchangestatusrequest.merchantaccount = merchantaccount; ddchangestatusrequest.confirmationnumber = "123456"; // A valid confirmation number from a previous mandate or echeck; ddchangestatusrequest.status = "C"; //Perform the Web Services call to process the charge DirectDebitServiceV1 ddservice = new DirectDebitServiceV1(); DDCheckResponseV1 ddtxnresponse = ddservice.changestatus(ddcheckrequest); // Print out the result String responsetxt = ddtxnresponse.code + " - " + ddtxnresponse.decision + " - " + ddtxnresponse.description; 2-30

45 juillet 2014 Diagramme de transaction ddchangestatusrequest responsetxt += "Details:" + Environment.NewLine; if (ddtxnresponse.detail!= null) { for (int i = 0; i < ddtxnresponse.detail.length; i++) { responsetxt += " - " + ddtxnresponse.detail[i].tag + " - " + ddtxnresponse.detail[i].value + Environment.NewLine; } } responsetxt = responsetxt.replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ddtxnresponse.decision); } Diagramme de transaction ddchangestatusrequest L objet de document ddchangestatusrequestv1 respecte la structure suivante : Éléments de transaction ddchangestatusrequestv1 L objet de document ddchangestatusrequestv1 peut contenir les éléments suivants : Tableau 2-8 : Éléments de transaction ddchangestatusrequestv1 Element Child Element Required Type Description merchantaccount accountnum Oui Chaîne Max = 10 Il s agit du numéro de compte de marchand. Guide de référence de l API pour les Services Web

46 Transactions par prélèvement automatique (débit direct) juillet 2014 Tableau 2-8 : Éléments de transaction ddchangestatusrequestv1 (suite) Element Child Element Required Type Description storeid Oui Chaîne Max = 80 storepwd Oui Chaîne Max = 20 confirmationnumber Conditionnel Chaîne Max = 20 Il s agit de l identifiant du magasin traitant la transaction ; il sert à authentifier la requête. NETBANX le définit et le fournit au marchand comme élément du processus d intégration. Il s agit du mot de passe du magasin traitant la transaction ; il sert à authentifier la requête. NETBANX le définit et le fournit au marchand comme élément du processus d intégration. Cette valeur indique la transaction pour laquelle vous avez demandé une modification d état. Il s agit du confirmationnumber retourné par NETBANX en réponse à la requête initiale. status Oui Énumération Il s agit du nouveau code d état de la transaction. Les valeurs possibles sont : C Complété RE Retourné W En attente X Annulée Création de updatemandaterequest (mise à jour du mandat) Seuls les marchands qui traitent des prélèvements automatiques SEPA peuvent effectuer ce type de requête. Vous pouvez modifier un mandat existant en effectuant une demande de modification de mandat. En réalité, vous créez un nouveau mandat à partir des informations du mandat existant, mais en y ajoutant de nouvelles informations (par exemple, un nouveau numéro de compte bancaire). Lorsque vous soumettez une requête ddupdatemandaterequestv1, NETBANX règle l état du mandat à T (Transférée). Un nouveau mandat est créé à partir des informations du mandat existant. Cependant, les trois valeurs suivantes ne sont pas modifiées si vous les précisez dans la demande de modification : mandatereference accountnum routingnum Si vous le précisez dans la demande, les nouvelles valeurs entrées relativement à ces éléments sont importées dans le nouveau mandat. L état du nouveau mandat sera identique à celui du mandat existant, soit PCA (Approbation du client en attente) ou AP (Mandat approuvé). Le nouveau mandat sera lié au mandat existant, de sorte que le système sache que les informations du mandat existant ont été transférées dans le nouveau mandat. 2-32

47 juillet 2014 Exemple de transaction updatemandaterequest C# NETBANX répond à votre demande de modification de mandat par une réponse ddcheckresponsev1. Dans cette réponse, la valeur confirmationnumber sert à identifier le nouveau mandat. Exemple de transaction updatemandaterequest C# Voici un exemple de transaction ddupdatemandaterequest en C#. // Prepare the call to the Direct Debit Web Service DDUpdateMandateRequestV1 ddupdatemandaterequest = new DDUpdateMandateRequestV1(); MerchantAccountV1 merchantaccount = new MerchantAccountV1(); merchantaccount.accountnum = " "; merchantaccount.storeid = "mystoreid"; merchantaccount.storepwd = "mystorepwd"; ddupdatemandaterequest.merchantaccount = merchantaccount; ddupdatemandaterequest.confirmationnumber = "123456"; // A valid confirmation number from a previous mandate or echeck; ddupdatemandaterequest.mandatereference = "NL95ZZZ _TEST7A"; //Perform the Web Services call to process the charge DirectDebitServiceV1 ddservice = new DirectDebitServiceV1(); DDCheckResponseV1 ddtxnresponse = ddservice.updatemandate(ddcheckrequest); // Print out the result String responsetxt = ddtxnresponse.code + " - " + ddtxnresponse.decision + " - " + ddtxnresponse.description; responsetxt += "Details:" + Environment.NewLine; if (ddtxnresponse.detail!= null) { for (int i = 0; i < ddtxnresponse.detail.length; i++) { responsetxt += " - " + ddtxnresponse.detail[i].tag + " - " + ddtxnresponse.detail[i].value + Environment.NewLine; } } responsetxt = responsetxt.replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ddtxnresponse.decision); } Diagramme de transaction ddupdatemandaterequestv1 L objet de document ddupdatemandaterequestv1 respecte la structure suivante : Guide de référence de l API pour les Services Web

48 Transactions par prélèvement automatique (débit direct) juillet 2014 Éléments de transaction ddupdatemandaterequestv1 L objet de document ddupdatemandaterequestv1 peut contenir les éléments suivants : Tableau 2-9 : Éléments de transaction ddupdatemandaterequestv1 Élément Élément enfant Requis Type Description merchantaccount accountnum Oui Chaîne Max = 10 storeid Oui Chaîne Max = 80 storepwd Oui Chaîne Max = 20 confirmationnumber Facultatif Chaîne Max = 20 mandatereference Facultatif Chaîne Max = 10 Pour SEPA, Max = 35 Il s agit du numéro de compte de marchand. Il s agit de l identifiant du magasin traitant la transaction ; il sert à authentifier la requête. NETBANX le définit et le fournit au marchand comme élément du processus d intégration. Il s agit du mot de passe du magasin traitant la transaction ; il sert à authentifier la requête. NETBANX le définit et le fournit au marchand comme élément du processus d intégration. Cette valeur indique le mandat que vous voulez modifier. Il s agit du numéro de confirmation retourné par NETBANX en réponse à la requête initiale. Il s agit de la référence du mandat permettant de porter les frais au compte. Cette valeur est retournée pour le paramètre mandatereference en réponse à la requête ddmandaterequestv1. Vous devrez peut-être modifier la valeur mandatereference, par exemple, si les modalités de facturation ont changé et que les autres informations dans le mandat demeurent identiques. 2-34

49 juillet 2014 Traitement de la réponse Tableau 2-9 : Éléments de transaction ddupdatemandaterequestv1 (suite) Élément Élément enfant Requis Type Description accountnum Conditionnel Chaîne Max = 17 Si IBAN, Max = 32 routingnum Conditionnel Chaîne Min = 6 Max = 9 Si BIC, Min = 8 Max = 11 Pour les transactions SEPA, il s agit du numéro IBAN (numéro de compte bancaire international) du client. Vous devrez peut-être modifier la valeur accountnum, par exemple, si les frais sont désormais portés à un compte différent de la même banque (c.-à-d., il n est pas nécessaire de modifier le code BIC). Pour les transactions SEPA, il s agit du code BIC (code identificateur de banque) du compte bancaire du client. Vous devrez peut-être modifier la valeur routingnum, par exemple, si un client a changé de banque. Dans ce cas, il faudra aussi modifier la valeur accountnum. * Au moins un des trois éléments suivants doit être indiqué dans la requête : mandatereference, accountnum ou routingnum. Traitement de la réponse Une transaction ddcheckresponsev1 respecte la structure suivante : Guide de référence de l API pour les Services Web

50 Transactions par prélèvement automatique (débit direct) juillet 2014 Les éléments suivants sont pertinents dans le cas d une réponse ddcheckresponsev1 : Tableau 2-10 : Éléments de réponse ddcheckresponsev1 Élément Élément enfant Requis Type Description requestid Facultatif Il s agit du seul numéro d identification unique envoyé par NETBANX pour un enregistrement si ce dernier a été traité dans un fichier séquentiel. confirmationnumber Oui Chaîne Max = 20 Il s agit du numéro de confirmation retourné par NETBANX. Si cette valeur est retournée en réponse à une ddmandaterequestv1, elle sert à identifier le nouveau mandat. 2-36

51 juillet 2014 Traitement de la réponse Tableau 2-10 : Éléments de réponse ddcheckresponsev1 (suite) Élément Élément enfant Requis Type Description merchantrefnum Conditionnel Chaîne Max = 255 mandatereference Oui Chaîne Max = 20 Il s agit d un numéro d identification (ID) unique, associé à chaque requête. La valeur est créée par le marchand et envoyée en tant qu élément de la requête. Cette valeur n est retournée qu en réponse à une lookuprequest. Ceci est la référence du mandat retournée par NETBANX. Il s agit de la valeur entrée dans la requête ou, si celle-ci était erronée, d une valeur générée par le système NETBANX. Pour les transactions SEPA, ceci est la référence du mandat créée par le marchand dans la requête. decision Oui Énumération Il s agit de l état de la transaction. Une des valeurs suivantes sera retournée : Accepted La transaction a été traitée. Error La tentative de transaction a échoué en raison d une erreur. Declined La transaction a été refusée avant qu elle soit envoyée pour traitement. Not Found La requête de consultation ne correspond à aucun résultat. code Oui Entier Il s agit d un code numérique servant à catégoriser la réponse. Consultez la rubrique Codes de réponse à la page B-1. actioncode Facultatif Énumération Cela indique l action à effectuer. Les valeurs suivantes sont possibles : C = Erreur de paramètre du client. Les renseignements fournis par le client sont incorrects. Confirmez les renseignements auprès du client. D = Ne pas réessayer. Les tentatives subséquentes échoueront. M = Erreur de paramètre du marchand. Les renseignements fournis par votre application sont incorrects. Vérifiez vos renseignements. R = Réessayer. Le problème est temporaire. La prochaine tentative réussira probablement. description Facultatif Chaîne Max = 100 Il s agit de la description accessible à l utilisateur de l élément code. Guide de référence de l API pour les Services Web

52 Transactions par prélèvement automatique (débit direct) juillet 2014 Tableau 2-10 : Éléments de réponse ddcheckresponsev1 (suite) Élément Élément enfant Requis Type Description detail tag Facultatif Chaîne Max = 1024 value Facultatif Chaîne Max = 30 Il s agit de la classification de l élément détail. Il s agit de la description du détail. txntime Oui datetime Il s agit de la date et de l heure du traitement de la transaction par NETBANX. status Facultatif code Conditionnel Énumération Il s agit de l état de la première transaction qui correspond à la requête de consultation. Les valeurs possibles sont : AP Mandat approuvé (Approved mandate) C Lot complet (Complete batch) CB Récupérée (Clawed back) CL Transaction traitée (Cleared transaction) DE Refusée (Declined) DI Contestée (Disputed) E Erreur lot (Error batch) EX Expirée (Expired) F Échec (Failed) GR Bon pour renversement (Good for reversal) MI Intervention manuelle requise (Manual intervention required) PCA Approbation du client en attente (Pending customer approval) PR1 Re-Présentée 1 (Re-Presented 1) PR2 Re-Présentée 2 (Re-Presented 2) PX Annulation en attente (Pending cancel) RE Retournée (Returned) REF Rejet définitif (Rejected final) RV Inversée (Reversed) T Transférée (Transferred) W En attente (Pending) X Annulée (Cancelled) 2-38

53 juillet 2014 Traitement de la réponse Tableau 2-10 : Éléments de réponse ddcheckresponsev1 (suite) Élément Élément enfant Requis Type Description effectivedate Conditionnel datetime Il s agit de la date et de l heure où l état de la requête de consultation entre en vigueur. Lorsqu elle est indiquée dans la paire tag/value pour l élément detail d une réponse à une requête de mandat, ceci est la date à laquelle le mandat devient actif (cinq jours après la mise en lot). Vous pouvez soumettre une demande de prélèvement à cette date à minuit ou postdater le prélèvement en réglant la valeur txntime à cette date ou à une date ultérieure. Si vous soumettez une demande de prélèvement dont la date est antérieure à la date d entrée en vigueur du mandat, indiquée par la valeur effectivedate, vous obtiendrez un message d erreur. currency Facultatif Chaîne La valeur figure dans les codes de devises du Tableau 3-15 : Codes de devises à la page Cette valeur n est retournée qu en réponse à une lookuprequest. amount Facultatif Chaîne Max = ,99 Il s agit du montant de la première transaction qui correspond à la requête de consultation. transaction Facultatif Cette valeur n est retournée qu en réponse à une lookuprequest. Toutes les transactions qui correspondent à la requête de consultation sont retournées ici. confirmationnumber Conditionnel Chaîne Max = 20 merchantrefnum Facultatif Chaîne Max = 255 Il s agit du numéro de confirmation retourné par NETBANX pour une transaction précédente. Il s agit d un numéro d identification (ID) unique, associé à chaque requête. La valeur est créée par le marchand et envoyée en tant qu élément de la requête. Cette valeur n est retournée qu en réponse à une lookuprequest. txntime Conditionnel datetime Il s agit de la date et de l heure du traitement de la transaction par NETBANX. status Conditionnel On retrouve les éléments code et effectivedate pour la transaction. Pour obtenir des détails, consultez l élément status présenté dans le tableau cidessus. Guide de référence de l API pour les Services Web

54 Transactions par prélèvement automatique (débit direct) juillet 2014 Tableau 2-10 : Éléments de réponse ddcheckresponsev1 (suite) Élément Élément enfant Requis Type Description amount Conditionnel Chaîne Max = ,99 Il s agit du montant de la requête de transaction. Pour traiter la réponse : 1. Obtenez les détails de la réponse qui sont accessibles à partir des modes get() de la réponse. String responsetxt = ddtxnresponse.code + " - " + ddtxnresponse.decision + " - " + ddtxnresponse.description; responsetxt += "Details:" + Environment.NewLine; if (ddtxnresponse.detail!= null) { for (int i = 0; i < ddtxnresponse.detail.length; i++) { responsetxt += " - " + ddtxnresponse.detail[i].tag + " - " + ddtxnresponse.detail[i].value + Environment.NewLine; } } responsetxt = responsetxt.replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ddtxnresponse.decision); } 2. Traitez la réponse en fonction de l élément decision. Vous insérez le code de gestion approprié à votre application. Vous pouvez également consulter l élément code pour obtenir un contrôle plus serré de votre application. Pour obtenir plus de détails, consultez la rubrique Codes de réponse à la page B

55 CHAPITRE 3 Transactions par carte de crédit ou de débit Introduction Ce chapitre décrit comment traiter les transactions par carte de crédit ou de débit à l aide du Service Web de traitement des transactions. Les opérations suivantes sont prises en charge : Tableau 3-1 : Opérations prises en charge Opération Description Type de requête Authorization (autorisation) Purchase (achat) Verification (vérification) Authorization Reversal (inversion d autorisation) Credit (crédit) Settlement (règlement) Stored Data Authorization (autorisation à partir de données mémorisées) Stored Data Purchase (achat partir de données mémorisées) Vous permet d autoriser un montant sur la carte de crédit ou de débit d un client. Le montant autorisé doit être réglé au cours d une transaction de règlement ultérieure. Vous permet d autoriser et de régler un montant sur la carte de crédit ou de débit d un client à l aide d une seule transaction. Vous permet d exécuter une vérification AVS ou CVD sur la carte de crédit d un client, sans imputer de montant sur cette carte. Vous permet d inverser une partie ou la totalité d une autorisation existante, pourvu qu aucun règlement (complet ou partiel) n ait été traité à l'égard de cette autorisation. Ce type de transaction ne fonctionne pas pour les transactions d'achat ; cette transaction n est utilisée que pour les autorisations. Vous permet d annuler le débit d un montant déjà réglé sur une carte de crédit ou de débit. Vous pouvez créditer la totalité ou une partie d un règlement existant. Vous permet de régler un montant qui a préalablement été autorisé sur une carte de crédit ou de débit. Vous pouvez régler la totalité ou une partie d une autorisation existante. Vous permet d autoriser un montant sur la carte de crédit ou de débit d un client à l aide des données sur le client qui sont mémorisées dans notre base de données. Vous n avez qu à fournir le minimum de renseignements, ce qui vous permet de gagner du temps et de réduire les efforts. Vous permet d autoriser et de régler un montant sur la carte de crédit ou de débit d un client à l aide de données sur le client qui sont mémorisées dans notre base de données. Vous n avez qu à fournir le minimum de renseignements, ce qui vous permet de gagner du temps et de réduire les efforts. Consultez la rubrique Bâtir des requêtes d achat, d autorisation ou de vérification à la page 3-5. Consultez la rubrique Bâtir des requêtes d inversion d autorisation à la page Consultez la rubrique Bâtir des requêtes de règlement et de crédit à la page Consultez la rubrique Bâtir des requêtes de données mémorisées à la page Guide de référence de l API pour les Services Web

56 Transactions par carte de crédit ou de débit juillet 2014 Tableau 3-1 : Opérations prises en charge Opération Description Type de requête Cancel (annulation) Payment (paiement) Independent Credit (crédit indépendant) Information Lookup (consultation des données) Enrollment Lookup (consultation d inscription) Authentication (authentification) Vous permet d annuler une transaction de crédit, de règlement, de paiement, ou de crédit indépendant. Vous pouvez annuler une de ces transactions pourvu qu elle soit En attente, ce qui est habituellement le cas avant minuit le jour où la requête est faite. Dans certains cas, vous pouvez trouver des transactions de crédit plus anciennes En attente. Vous permet de créditer un montant sur la carte de crédit ou de débit d un client. La transaction de paiement n est pas liée à une autorisation existante antérieure ; le montant de la transaction n est donc pas limité de cette manière. Vous permet de créditer un montant sur la carte de crédit d un client. La transaction de crédit indépendant n est pas liée à une autorisation existante antérieure ; le montant de la transaction n est donc pas limité de cette manière. Vous permet de produire un rapport à l aide de l API pour une plage de temps que vous précisez, afin de recevoir les données concernant les transactions traités par un compte de marchand. Vous permet d établir si la carte de crédit du client est inscrite à notre programme 3D Secure. Vous permet d'envoyer une requête d'authentification, afin de valider le mot de passe d un titulaire de carte dans le cas des cartes de crédit inscrites au programme 3D Secure. Consultez la rubrique Bâtir des requêtes d annulation à la page Consultez la rubrique Bâtir des requêtes de paiement/crédit indépendant à la page Consultez la rubrique Bâtir des requêtes de consultation des données à la page Consultez la rubrique Bâtir des requêtes de consultation d inscription à la page Consultez la rubrique Bâtir des requêtes d authentification à la page La disponibilité des types d opérations pour les cartes de crédit est attribuée aux marchands sur une base individuelle, puisque ce ne sont pas toutes les banques des marchands qui acceptent toutes les opérations. Si vous avez des questions, communiquez avec votre gestionnaire de compte. Les opérations Authorization, Purchase et Verification acceptent l objet de document ccauthrequestv1. Les opérations Authorization Reversal acceptent l objet de document ccauthreversalrequestv1. Les opérations de Settlement et Credit acceptent l objet de document ccpostauthrequestv1. Les opérations Stored Data acceptent l objet de document ccstoreddatarequestv1. Les opérations Cancel Settle, Cancel credit et Cancel payment acceptent l objet de document cccancelrequestv1. L opération Payment et Independent Credit acceptent l objet de document ccpaymentrequestv1. L opération Information Lookup accepte l objet de document cctxnlookuprequestv1. L opération Enrollment Lookup accepte l objet de document ccenrollmentlookuprequestv1. L opération Authentication accepte l objet de document ccauthenticaterequestv1. Toutes les opérations retournent une réponse cctxnresponsev1. 3-2

57 juillet 2014.Exemple.NET.Exemple.NET Pour bâtir l exemple pour.net : 1. Créez un nouveau projet. 2. Ajoutez une référence Web. Guide de référence de l API pour les Services Web