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 mars 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 (requêtes de mandat) Guide de référence de l API pour les Services Web 1.0 III

4 mars 2014 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 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 É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 IV

5 mars 2014 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 ddmandaterequest A-7 Exemple HTML mandaterequest A-8 changestatusrequest A-9 Exemple HTML changestatusrequest A-10 Requêtes relatives à une carte de crédit A-10 Guide de référence de l API pour les Services Web 1.0 V

6 mars 2014 Achat, autorisation et vérification A-10 Exemple HTML Autorisation A-12 Inversion d autorisation A-14 Exemple HTML Inversion d autorisation A-14 Règlement et crédit A-15 Exemple HTML Règlement A-16 Autorisation ou achat à partir de données mémorisées A-17 Exemple HTML Autorisation à partir de données mémorisées A-17 Annuler un règlement, un crédit, un paiement, ou un crédit indépendant A-18 Exemple HTML Annuler A-19 Requête de paiement A-20 Exemple HTML Paiement A-21 Consultation des données A-22 Exemple HTML Consultation des données A-23 Consultation d inscription A-24 Exemple HTML Consultation d inscription A-25 Authentification A-26 Exemple HTML Authentification A-26 Requêtes relatives au service de consultation des données A-27 Exemple HTML ILS A-28 HTTP Post Exemples A-29 HTTP Post Réponses aux requêtes A-29 B Codes de réponse Aperçu B-1 Codes de réponse B-1 Codes d action B-20 Codes de refus B-20 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 au Royaume-Uni 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 mars 2014 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) Information Lookup (consultation des données) 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. 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. 1-2

9 mars 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 Enrollment Lookup (consultation d inscription) Authentication (authentification) Description 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. Apache Axis 1.4, The Apache Software Foundation Apache Axis2, 1.2, The Apache Software Foundation Guide de référence de l API pour les Services Web

10 Services Web de NETBANX mars 2014 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 : 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 1-4

11 mars 2014 Caractéristiques de sécurité 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 R S U W X 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. 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. Guide de référence de l API pour les Services Web

12 Services Web de NETBANX mars 2014 Tableau 1-5 : Codes AVS (suite) Lettre du code Y Z Explication 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. Base de données des éléments négatifs 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. 1-6

13 mars D Secure 3D Secure 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 : 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. Guide de référence de l API pour les Services Web

14 Services Web de NETBANX mars

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 Type de requête verify (vérification) charge (facturation) credit (crédit) updateshippinginfo lookuprequest mandaterequest changestatusrequest 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 au Royaume-Uni 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. Consultez la rubrique Bâtir des requêtes de facturation, de vérification ou de crédit à la page 2-3. Consultez la rubrique Création de requêtes updateshippinginfo à la page Consultez la rubrique Création de lookuprequest (requêtes de consultation) à la page Consultez la rubrique Création de mandaterequest (requêtes de mandat) à la page Consultez la rubrique Création de changestatusrequest (requêtes de modification d état) à la page 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. Guide de référence de l API pour les Services Web

16 Transactions par prélèvement automatique (débit direct) mars 2014 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. 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 mars 2014 Bâtir des requêtes de facturation, de vérification ou de crédit 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-3. Consultez la rubrique Création de requêtes updateshippinginfo à la page 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-6. 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. Guide de référence de l API pour les Services Web

18 Transactions par prélèvement automatique (débit direct) mars 2014 // 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++) { 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-4

19 mars 2014 Diagramme de transaction ddcheckrequestv1 Diagramme de transaction ddcheckrequestv1 L objet de document ddcheckrequestv1 respecte la structure suivante : Guide de référence de l API pour les Services Web

20 Transactions par prélèvement automatique (débit direct) mars 2014 Éléments de transaction ddcheckrequestv1 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. 2-6

21 mars 2014 Éléments de transaction ddcheckrequestv1 Tableau 2-2 : Éléments de transaction ddcheckrequestv1 (suite) Élément Élément enfant Requis Type Description 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 payee Conditionnel Chaîne Max = 81 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 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. 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 Il s agit de la ville dans laquelle la banque est située. Cet élément n est requis que pour certains pays. Guide de référence de l API pour les Services Web

22 Transactions par prélèvement automatique (débit direct) mars 2014 Tableau 2-2 : Éléments de transaction ddcheckrequestv1 (suite) Élément Élément enfant Requis Type Description check (suite) mandatereference Conditionnel Chaîne Max = 10 Ceci est la référence du mandat permettant de porter les frais au compte bancaire au Royaume- Uni. Cette valeur est retournée pour le paramètre confirmationnumber en réponse à la ddmandaterequestv1. 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 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 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. 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 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. 2-8

23 mars 2014 Éléments de transaction ddcheckrequestv1 Tableau 2-2 : Éléments de transaction ddcheckrequestv1 (suite) Élément Élément enfant Requis Type Description personalid idnumber Facultatif Chaîne Max = 20 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) 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. Guide de référence de l API pour les Services Web

24 Transactions par prélèvement automatique (débit direct) mars 2014 Tableau 2-2 : Éléments de transaction ddcheckrequestv1 (suite) Élément Élément enfant Requis Type Description 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 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 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. 2-10

25 mars 2014 Éléments de transaction ddcheckrequestv1 Tableau 2-2 : Éléments de transaction ddcheckrequestv1 (suite) Élément Élément enfant Requis Type Description customerip Facultatif Chaîne Max = 50 Il s agit de l adresse IP du client. 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. sdk version Conditionnel Chaîne Max = 20 platform Conditionnel Chaîne Max = 10 provider Conditionnel Chaîne Max = 20 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. 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 Il s agit de données supplémentaires que le marchand peut inclure dans la requête de transaction. Guide de référence de l API pour les Services Web