AMEX Web Services IP Payments HTTPS Comm Guide

Transcription

Guide de transmission
Protocole HTTPS
Passerelle de paiement IP
Services Web
AMERICAN EXPRESS
Expansion du réseau
Renseignements confidentiels et privatifs d’American Express
POS020052, v2.3, 7 mai 2009
0903070
Exigences d’American Express en matière de confidentialité
Le présent document contient des secrets commerciaux et des
renseignements confidentiels et privatifs d’American Express. Il est
interdit au destinataire de le reproduire, de l’utiliser et de le
divulguer, en totalité ou en partie, sauf à seule fin d’évaluer les
spécifications et les systèmes qui y sont décrits.
© 2006-2009 American Express Travel Related Services Company, Inc. Tous droits réservés.
Aucune partie du présent document ne doit être reproduite sous quelque forme que ce soit ni
par aucun moyen, électronique ou mécanique, y compris un système d’archivage et de
recherche d’information, sans le consentement préalable écrit et explicite d’American Express
Travel Related Services Company, Inc.
Le présent document contient des secrets commerciaux ainsi que des renseignements
confidentiels et privatifs d’American Express et des sociétés membres de son groupe qui ne
doivent être divulgués à des tiers, en totalité ou en partie, sans le consentement écrit préalable
d’American Express.
0903070
Rens. priv. et conf. d’American Express
Guide de transmission HTTPS – Serv. Web
Liste des mises à jour
Numéro
Date
Réviseur
Approbateur
Description
2.3
05/07/09
R. Wong
B. Jones
Première diffusion de la version française.
7 mai 2009
POS020052 (0903070)
i
Page intentionnellement laissée en blanc.
ii
POS020052 (0903070)
7 mai 2009
Table des matières
1.0
Introduction....................................................................................................................... 1
2.0
Services de paiement IP offerts ........................................................................................ 3
2.1
Aperçu................................................................................................................................. 3
2.2
Conception fonctionnelle.................................................................................................... 3
2.3
Formats de fichier pris en charge........................................................................................ 4
3.0
Connectivité....................................................................................................................... 5
4.0
Message de demande......................................................................................................... 7
5.0
Message de réponse : navigateur et terminal ............................................................... 11
5.1
Messages de réponse reçus du serveur.............................................................................. 11
5.2
Messages d’erreur Java ..................................................................................................... 12
6.0
Transmission.................................................................................................................... 13
6.1
Exemple de message ISO 8583 dans le format TIM......................................................... 13
6.1.1
Validation de transfert SSL sur une nouvelle connexion TCP .......................................... 14
6.1.2
Envoi d’une commande HTTP POST............................................................................... 15
7.0
Marche à suivre pour créer un client test en Java ....................................................... 17
8.0
Marche à suivre pour créer un client test en .Net (C#)................................................ 19
8.1
Exemple d’un client C# .................................................................................................... 20
9.0
Marche à suivre pour créer un client test en C++........................................................ 21
9.1
Exemple d’un client C++ — Méthode Connect ............................................................... 22
9.2
Exemple d’un client C++ — Méthode Send..................................................................... 23
10.0
Refus, erreurs et pannes ................................................................................................. 25
11.0
Codes de pays et de région ............................................................................................. 27
7 mai 2009
POS020052 (0903070)
iii
iv
POS020052 (0903070)
7 mai 2009
1.0
Introduction
Le Guide de transmission – Protocole HTTPS – Passerelle de paiement IP – Services Web a été rédigé
pour les programmeurs des marchands, des sociétés de traitement autorisées, des développeurs indépendants et des fournisseurs de logiciels et de terminaux pour les aider à concevoir des interfaces pour les
communications avec les systèmes d’American Express.
Le présent document ne vise que les connexions utilisées pour transmettre les données. Les formats
de fichier et les définitions de champs sont fournis dans d’autres documents d’American Express (par
exemple, l’un des formats du message de demande d’autorisation est décrit dans le Guide mondial des
autorisations des opérations de crédit d’American Express).
7 mai 2009
POS020052 (0903070)
1
2
POS020052 (0903070)
7 mai 2009
2.0
Services de paiement IP offerts
2.1
Aperçu
Le présent document est fourni aux clients qui veulent envoyer différents messages de demandes
touchant les règlements financiers à American Express par l’entremise d’Internet, en accédant à des
adresses URL spécifiques d’American Express, qui sont fournies dans le présent guide. Il contient les
renseignements techniques nécessaires pour permettre aux marchands, aux sociétés de traitement
autorisées, aux développeurs indépendants et aux fournisseurs de logiciels et de terminaux de communiquer avec les systèmes d’American Express au moyen de la passerelle de paiement IP – Services
Web d’American Express.
Le présent guide fournit une explication sommaire des options URL proposées, la marche à suivre
pour accéder aux adresses URL et les exigences que doivent remplir le système du marchand ou du
fournisseur. Il ne présente aucune description des méthodes de saisie électronique des données et
d’autorisation d’American Express. Pour des renseignements à ces sujets, consultez le site Web
www.americanexpress.com/merchantspecs.
2.2
Conception fonctionnelle
La passerelle de paiement IP – Services Web d’American Express permet aux marchands et aux fournisseurs de transmettre des messages (autorisations et saisie électronique des données) en temps réel
par Internet. Le protocole HTTPS est utilisé pour offrir un accès sécurisé aux adresses URL de la
passerelle.
Les marchands et les fournisseurs utilisent la solution de passerelle de paiement IP – Services Web
d’American Express en accédant aux adresses URL appropriées. Les données du message de demande
sont incorporées dans une variable cachée dans la transmission à American Express; et une commande
HTTPS POST est utilisée pour transmettre ces données à la passerelle de paiement IP – Services Web
d’American Express. Aucun code d’utilisateur ni mot de passe ne sont nécessaires.
American Express utilise le protocole d’authentification SSL et transmet un certificat SSL dans le
message de validation de transfert retourné au terminal ou au système du marchand ou du fournisseur.
Le terminal ou le système doit accepter ce certificat.
Les systèmes d’American Express traitent la demande reçue et retournent une réponse dans une variable
cachée du message de réponse produit par American Express.
De plus amples explications sur ce processus sont fournies dans les sections qui suivent.
7 mai 2009
POS020052 (0903070)
3
2.3
Formats de fichier pris en charge
Au moment de rédiger le présent document, voici les formats de fichier de demande d’autorisation qui
sont pris en charge :
•
Guide des autorisations des opérations de crédit – POS020005
•
Guide mondial des autorisations des opérations de crédit – POS020041
•
Spécifications pour l’interface des terminaux – TIM – Services Web (format XML) – POS020050
•
Guide mondial des autorisations des opérations de crédit – Services Web (format XML) –
POS020054
•
Spécifications pour l’interface des terminaux – TIM – Services Web (terminal à propriété
exclusive, format autre que XML) – POS020055
•
Guide des autorisations des opérations de crédit par ligne commutée – Services Web –
POS020067
•
MULTILINK México and IDC Technical Specification – POS020068 (document en anglais
seulement)
4
POS020052 (0903070)
7 mai 2009
3.0
Connectivité
•
Les transactions doivent être envoyées à la passerelle de paiement IP – Services Web. Les adresses
URL pertinentes seront fournies par le représentant d’American Express.
•
Les spécifications détaillées pour le protocole HTTP/1.1 sont fournies dans le document RFC2616,
sur le site Web http://www.w3.org/Protocols/rfc2616/rfc2616.html. *
•
Les transactions sont transmises dans les en-têtes de la demande, dans le cas de la méthode POST.
À partir de la page 13, vous trouverez des exemples d’opérations transmises à la passerelle de
paiement IP – Services Web au moyen de la méthode POST.
*
Le document RFC2616 n'est présenté qu'en anglais sur cette page Web, mais il est possible d'en trouver des
versions françaises non officielles à l'aide de différents moteurs de recherche Internet.
7 mai 2009
POS020052 (0903070)
5
6
POS020052 (0903070)
7 mai 2009
4.0
Message de demande
•
Établissez une connexion HTTPS avec le nom de serveur fourni en utilisant le PROTOCOLE et
le PORT déterminés.
•
Les valeurs ci-dessous doivent être transmises dans l’en-tête du message de demande pour que la
passerelle de paiement IP d’American Express puisse les traiter.
•
–
Origin (origine)
–
Country (pays)
–
Region (région)
–
Message (Message)
–
MerchNbr (numéro d’établissement)
–
RtInd (code de routage)
Désignez le message de demande d’autorisation comme un train d’octets dans la variable cachée :
AuthorizationRequestParam
•
Le terminal établira une connexion avec l’adresse URL.
•
Lancez une commande HTTPS POST pour envoyer un message de demande à l’adresse URL de
la passerelle de paiement IP – Services Web d’American Express.
•
Le message de demande (ex., un message ISO ou la valeur XML d’autorisation) ne devrait pas
figurer dans les valeurs de l’en-tête. Les données du message doivent plutôt être transmises dans
la variable POST de la demande, c’est-à-dire dans la valeur clé AuthorizationRequestParam.
Pour des renseignements détaillés sur les en-têtes servant à désigner le terminal et le navigateur
utilisés pour transmettre le message de demande, voir les deux prochaines pages.
7 mai 2009
POS020052 (0903070)
7
4.0
Message de demande (suite)
En-tête pour désigner le navigateur – Message de demande
POST
POST /IPPayments/inter/CardAuthorization.do HTTP/1.1
Accept
image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/vnd.msexcel, application/vnd.ms-powerpoint, application/msword, application/xshockwave-flash, */*
Referer
<référent>
Accept-Language
en-us
Content-Type
Texte/en/clair
User-Agent
Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322; .NET
CLR 2.0.50727)
Host
<URL : fournie au marchand ou au fournisseur par le représentant
d’American Express>
Content-Length
<taille dynamique du message>
Cache-Control
Sans antémémoire
Connection
Persistante
origin
<nom du fournisseur> Remarque : les marchands qui conçoivent leur propre logiciel doivent utiliser <nom du
marchand>.
country
Voir le tableau des codes de pays et de région à la page 27.
region
message
Voir les types de message à la page 9.
MerchNbr
Numéro d’établissement
RtInd
Voir le tableau des codes de routage à la page 9.
En-tête pour désigner le terminal – Message de demande
POST
POST /IPPayments/inter/CardAuthorization.do HTTP/1.1
Accept-Language
en-us
Content-type
Texte/en/clair
User-Agent
Terminal;<nom du fournisseur>;<type de terminal>
Host
<URL : fournie au marchand ou au fournisseur par le représentant
d’American Express>
Content-Length
<taille dynamique du message>
Cache-Control
Sans antémémoire
Connection
Persistante
origin
<Nom du fournisseur>
country
region
message
Voir les types de message à la page 9.
MerchNbr
Numéro d’établissement
RtInd
Voir le tableau des codes de routage à la page 9.
Remarque : les noms de variable figurant dans la première colonne des tableaux ci-dessus sont sensibles à la casse.
8
POS020052 (0903070)
7 mai 2009
4.0
•
Message de demande (suite)
Code de routage (à utiliser dans la variable RtInd, voir la page précédente)
Code de routage
•
Description
000
Les données sont acheminées au réseau mondial des autorisations des opérations de crédit (pour tous
les marchands des États-Unis et ceux de certaines autres régions).
001
Les données sont acheminées à MultiLinks pour les marchands du Mexique.
002
Les données sont acheminées à MultiLinks pour les marchands des marchés en $US (IDC).
003
Les données sont acheminées à Stratus – Mexique.
004
Les données sont acheminées à Stratus – Argentine.
005
Les données sont acheminées à Stratus – PHX32.
006
Les données sont acheminées à Stratus – PHX36.
007
Les données sont acheminées à Stratus – SYD01.
008
Les données sont acheminées à Stratus – SIN01.
009
Les données sont acheminées à Stratus – HKG02.
010
Les données sont acheminées à Stratus – BSH07 UK (Brighton) – pour les marchands du Royaume-Uni,
de la Belgique (y compris le Luxembourg), la Hollande, la France, l’Italie, la Finlande et la Pologne.
011
Les données sont acheminées à Stratus FRA03 German (Francfort) – pour les marchands de l’Allemagne,
de la Suisse et de la Suède.
Types de message (à utiliser dans la variable message, voir la page précédente)
Type de message
Description
ISO MLMI
ISO 8583 v0 (nouveau) – Spécifications techniques MULTILINK pour le Mexique et IDC (région ALA).
ISO DLA
ISO 8583 v0 – Connexion directe en Argentine (région ALA).
ISO POSM
ISO 8583 v0 – PdV du Mexique (région ALA).
ISO POSA
ISO 8583 v0 – PdV de l’Argentine (région ALA)
ISO CAG
ISO 8583 v1 – Guide des autorisations des opérations de crédit (région ALA).
ISO GCAG
ISO 8583 v1 – Guide mondial des autorisations des opérations de crédit (É.-U. et région ALA)
XML GCAG
Guide mondial des autorisations des opérations de crédit (format XML) (É.-U.)
XML PIP
Spécifications pour l’interface des terminaux – TIM (format XML) (É.-U.)
ISO PIP
ISO 8583 v0 -- Spécifications pour l’interface des terminaux – TIM (É.-U. et région ALA)
WS DUAG
Guide des autorisations des opérations de crédit par ligne commutée (É.-U.)
EDC JAPA
Spécifications pour les terminaux de saisie électronique des données (région JAPA)
APACS
Spécifications APACS 30 pour les autorisations des opérations de crédit (région EMOA)
GICC
Protocole GICC pour les autorisations des opérations de crédit au PdV (région EMOA)
Les marchands et les fournisseurs doivent transmettre la variable ci-dessous dans le corps du message
de demande (dans les variables pour le navigateur et le terminal). La valeur entrée dans la variable
correspond au message de charge utile réelle.
Corps du message de demande – Navigateur et terminal
AuthorizationRequestParam=<Demande-autorisation-dynamique>
7 mai 2009
POS020052 (0903070)
9
10
POS020052 (0903070)
7 mai 2009
5.0
Message de réponse : navigateur et terminal
•
Lancez une commande HTTPS POST une fois connecté pour récupérer le message de réponse à
l’adresse URL de la passerelle de paiement IP – Services Web d’American Express.
•
Procédez ensuite à l’extraction du message de réponse à la demande d’autorisation dans le
contenu du train reçu du serveur.
En-tête – Message de réponse
(Status-Line)
HTTP/1.1 200 OK (si la transaction a réussie)
Connection
Fermer
Content-Language
en-us
Content-Type
Texte/en/clair
Date
<Date Mar, 18 Juil 2006 00:19:48 TU>
Server
IBM_HTTP_Server
Actual Response Message String
<message de réponse sous forme de chaîne de données>
5.1
Messages de réponse reçus du serveur
Code d’état
Description
200
OK – La demande a été traitée avec succès.
204
Aucune réponse – Le serveur a reçu la demande, mais il n’y a aucune information à retourner; le client devrait
garder le même type d’affichage de document, principalement pour permettre l’entrée de scripts sans modifier
le document. Ce scénario a lieu quand la passerelle IP attend une réponse interne d’un service connexe.
400
Erreur dans la demande -- La syntaxe de la demande était erronée ou il était impossible de répondre à la
demande en soi. Il peut y avoir quelques erreurs dans le CHEMIN ou des erreurs de connexion aux serveurs
appropriés.
404
Introuvable – Le serveur n’a rien trouvé qui correspondait au URI donné.
500
Erreur interne – Une condition imprévue s’est manifestée et le serveur n’a pas pu traiter la demande.
501
Non pris en charge – Le serveur ne prend pas en charge la fonction demandée.
502
Surcharge temporaire – Le serveur n’a pu traiter la demande en raison d’une forte utilisation (que ce soit des
services HTTP ou d’autres demandes). En principe, la situation devrait être temporaire.
7 mai 2009
POS020052 (0903070)
11
5.2
Messages d’erreur Java
Problème
Cause
java.net.SocketException
1. Le délai d’opération a expiré.
Hôte inaccessible.
2. Connexion impossible.
Une adresse invalide pourrait être à l’origine
de ce problème.
• Barre oblique « / » manquante dans le
chemin.
• Mauvaise adresse URL.
Vérifiez si l’adresse URL débute par
« HTTP » et non « HTTPS ».
java.net.UnknownHostException:
<host name>
Mauvaise adresse URL entrée par
l’utilisateur.
java.io.FileNotFoundException
Protocole invalide.
12
POS020052 (0903070)
7 mai 2009
6.0
Transmission
Le diagramme ci-dessous montre les concepts de base de la cryptographie et du traitement SSL exécutés
sur une transaction SSL.
De plus, il montre la circulation des messages de demande et de réponse HTTP POST, avec les en-têtes.
Le SSL est un procédé de chiffrement complexe qui ne nécessite pas qu’une clé secrète soit échangée
entre le client et le serveur avant le début de la transaction. Le SSL utilise des clés publiques et privées
pour fournir un chiffrement souple qui peut être établi au moment d’effectuer la transaction sécurisée.
Remarque : dans le diagramme ci-dessous, une demande lancée par un navigateur est utilisée comme
exemple de message POST. Le type de message peut varier selon le matériel utilisé (navigateur ou
terminal du marchand) pour transmettre la demande d’autorisation
6.1
Exemple de message ISO 8583 dans le format TIM
L’exemple ci-dessous représente un message ISO 8583 envoyé par un terminal en format TIM
(traitement par interfaces multiples). L’application de l’utilisateur « /IPPayments/inter/
CardAuthorization.do » transmettra les données sur la transaction à l’adresse URL de la
passerelle de paiement IP – Services Web.
Pour en savoir plus, consultez les Spécifications pour l’interface des terminaux – TIM – Services Web
d’American Express (POS020055).
Client
American Express
SYN
Une connexion sécurisée doit être établie pour cette session.
Le navigateur établit une connexion TCP sur le port 443 TCP
HTTPS.
ACK
7 mai 2009
POS020052 (0903070)
13
6.1.1
Validation de transfert SSL sur une nouvelle connexion TCP
Client
American Express
CLIENT_HELLO
Le client envoie une commande CLIENT_HELLO au serveur,
qui doit comprendre ce qui suit :
• Version SSL et TLS supérieure prise en charge par le
client.
• Algorithmes de chiffrement pris en charge, en ordre de
préférence.
• Méthodes de compression des données prises en charge.
• Code de session. (Pour les nouvelles sessions SSL, le
code de session = « 0 ».)
• Le fichier aléatoire du client pour la création de clés.
SERVER_HELLO
Le serveur envoie une commande SERVER_HELLO au
client, qui doit comprendre ce qui suit :
• La version SSL ou TLS à utiliser pour la session SSL.
• L’algorithme de chiffrement à utiliser.
• La méthode de compression des données à utiliser.
Remarque : pour le moment, aucun algorithme de compression n’est défini pour la version SSL et TLS 3.
• Le code de session pour la présente session SSL.
• Le fichier aléatoire du serveur pour la création des clés.
CERTIFICATE
Le serveur envoie une commande CERTIFICATE, qui inclut
le certificat, la clé publique et la signature d’authentification
du serveur. Le certificat de l’organisme de certification qui
attribue les certificats au serveur peut aussi être joint, avec
d’autres certificats.
SERVER_DONE
Le serveur envoie une commande SERVER_DONE, qui
indique que cette étape de la validation du transfert SSL est
terminée. Si le client est authentifié, d’autres commandes
circulent entre le client et le serveur.
CERTIFICATE_VERIFY
Le client vérifie le certificat du serveur, puis envoie une commande CERTIFICATE_VERIFY.
CHANGE_CIPHER_SPEC
Le client envoie une commande CHANGE_CIPHER_SPEC,
qui indique que les données dans les dossiers SSL subséquents envoyées par le client au cours de la présente session
SSL seront chiffrées.
Remarque : les en-têtes SSL de 5 octets ne sont pas chiffrés.
FINISHED
Le client envoie la commande FINISHED, qui contient un
sommaire de toutes les commandes de validation de transfert
SSL exécutées jusqu’à présent. L’utilisation de la commande
FINISHED permet de s’assurer que toutes les commandes
ultérieurement échangées entre le client et le serveur ont bel
et bien été reçues.
14
POS020052 (0903070)
7 mai 2009
6.1.2
Envoi d’une commande HTTP POST
Client
American Express
HTTP POST
Le client envoie une commande HTTP POST, qui contient les
données du marchand, au moyen de la connexion TCP fraîchement établie. Voir l’exemple de commande HTTP POST
ci-dessous.
POST : /IPPayments/inter/CardAuthorization.do HTTP/1.1
Accept : image/gif, image/x-xbitmap, image/jpeg, image/pjpeg,
application/vnd.ms-excel, application/vnd.ms-powerpoint,
application/msword, application/x-shockwave-flash, */*
Referer : <espace - jsp ou page à laquelle l’application fait référence.>
Accept-Language : en-us
Content-Type : Texte/en/clair
User-Agent : Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR
1.1.4322; .NET CLR 2.0.50727
Host : qwww215.americanexpress.com
Content-Length : <taille dynamique du message>
Cache-Control : Sans antémémoire
Connection : Persistante
Origin : <nom du fournisseur>
Country : 840
Region : USA
Message : ISO TIM
MerchNbr : 1234567890
RtInd : 000
Le marchand doit envoyer la variable ci-dessous dans le corps du message.
---------------------------------------------------------AuthorizationRequestParam=<Authorization Request>
---------------------------------------------------------HTTP 100 Continue
Le client devrait compléter sa demande. Cette réponse
provisoire sert à informer le client que la partie initiale de la
demande a été reçue et qu’elle n’a pas encore été rejetée par
le serveur. Le client devrait poursuivre en envoyer le reste de
sa demande ou, si celle-ci est déjà complète, ignorer cette
réponse. Le serveur doit envoyer une réponse finale une fois
que la demande est complète.
TCP (ACK)
Le serveur Web envoie un message TCP ACK pour accuser
réception des deux segments TCP de la commande HTTP
POST.
HTTP 200 OK
Le serveur Web accuse réception de la commande HTTP
POST. Voir l’exemple d’en-tête HTTP POST ci-dessous.
(Status-Line) : HTTP/1.1 200 OK
Connection : Close
Content-Language : en_US
Content-Type : text/html; charset=ISO-8859-1
Date : <Date Mar, 18 Juil 2006 11:25:07 TU>
Server : IBM_HTTP_Server
---------------------------------------------------------La réponse est envoyée au marchand sous forme de chaîne.
----------------------------------------------------------
7 mai 2009
POS020052 (0903070)
15
6.1.2
Envoi d’une commande HTTP POST (suite)
Client
American Express
TCP (ACK)
Commande TCP ACK pour le segment TCP, qui contient
« HTTP 200 OK ».
TCP (FIN)
Le serveur commence le processus de libération de la
connexion TCP en envoyant un avis de fermeture.
TCP (FIN)
Le client commence le processus de libération de la
connexion TCP.
TCP (ACK)
TCP (FIN)
Le serveur Web libère la connexion TCP.
TCP (ACK)
Remarque : au moment de rédiger le présent document, American Express ne prend pas en charge les
reprises de session SSL. Actuellement, American Express ne prend en charge qu’une suite de chiffrement SSL : TLS_RSA_WITH_RC4_128_MD5 – 0x04.
16
POS020052 (0903070)
7 mai 2009
7.0
Marche à suivre pour créer un client test en Java
Le code Java est utilisé dans l’exemple ci-dessous pour établir une connexion et envoyer un message
de demande d’autorisation dans la variable cachée. Le texte en gras représente des commentaires.
//ÉTABLISSEMENT DE LA CONNEXION
{
... (code du client)
URL url = nouvelle URL("https://qwww215.americanexpress.com/IPPayments/inter/CardAuthorization.do");
URLConnection conn = url.openConnection();
//EN-TÊTES POUR LA COMMANDE SET – Valeurs de l’objet connexion
conn.setRequestProperty("POST", "/IPPayments/inter/CardAuthorization.do HTTP/1.1" );
conn.setRequestProperty("Accept-Language", "en-us" );
conn.setRequestProperty("Content-Type", "text/en/clair" );
conn.setRequestProperty("User-Agent", "Application" );
conn.setRequestProperty("Host", "qwww215.americanexpress.com" );
conn.setRequestProperty("Content-Length", "370" );
conn.setRequestProperty("Cache-Control", "Sans antémémoire" );
conn.setRequestProperty("Connection", "Persistante" );
conn.setRequestProperty("origin", "" );
conn.setRequestProperty("country", "" );
conn.setRequestProperty("region", "" );
conn.setRequestProperty("message", "" );
conn.setRequestProperty("MerchNbr", "" );
conn.setRequestProperty("RtInd", "" );
conn.setDoInput(true);
conn.setDoOutput(true);
conn.setUseCaches(false);
//Inscription du message de charge utile en données POST
String stArgs = "AuthorizationRequestParam = Actual Payload Message";
DataOutputStream out = new
DataOutputStream(conn.getOutputStream());
out.writeBytes(stArgs);
System.out.println(out.toString());
out.flush();
out.close();
... (code du client)
}
•
Une fois la demande du marchand ou du fournisseur envoyée à la passerelle de paiement IP –
Services Web, American Express retourne au terminal ou au système du marchand le certificat
du serveur.
•
Le terminal ou le système accepte le certificat.
•
La passerelle de paiement IP – Services Web d’American Express continue à traiter le message.
7 mai 2009
POS020052 (0903070)
17
18
POS020052 (0903070)
7 mai 2009
8.0
Marche à suivre pour créer un client test en .Net (C#)
•
Créez un client C# à l’aide de Visual Studio 2005.
•
Vous trouverez ci-dessous une liste des classes, incluses dans .Net Framework 2.0. Les utilisateurs
peuvent s’en servir pour concevoir leur client dans le langage C#.
Classe HttpWebRequest
Fournit une implémentation propre à HTTP de la classe WebRequest.
HttpWebRequest : WebRequest, ISerializable – La classe HttpWebRequest appuie les propriétés
et les méthodes définies dans la classe WebRequest ainsi que les autres propriétés et méthodes
qui permettent à l’utilisateur d’interagir directement avec les serveurs au moyen du protocole
HTTP.
Classe HttpWebResponse
Cette classe appuie les utilisations propres à HTTP des propriétés et des méthodes de la classe
WebResponse. Elle sert à concevoir des applications HTTP client autonomes pour l’envoi de
demandes HTTP et la réception de réponses HTTP.
Voir l’extrait de code à la page suivante.
7 mai 2009
POS020052 (0903070)
19
8.1
Exemple d’un client C#
public virtual string GetResponse(string Uri, string RequestMethod)
{
//Méthode utilisée pour la demande est « POST »
HttpWebRequest webrequest = CreateWebRequest(Uri,RequestMethod);
BuildReqStream(ref webrequest);
HttpWebResponse webresponse;
webresponse = (HttpWebResponse)webrequest.GetResponse();
Encoding enc = System.Text.Encoding.GetEncoding(1252);
StreamReader loResponseStream = new StreamReader(webresponse.GetResponseStream(),enc);
string Response = loResponseStream.ReadToEnd();
loResponseStream.Close();
webresponse.Close();
}
return Response;
public virtual HttpWebRequest CreateWebRequest(string uri,string RequestMethod)
{
HttpWebRequest webrequest = (HttpWebRequest) WebRequest.Create(uri);
webrequest.KeepAlive = false;
webrequest.Method = RequestMethod;
//Information sur l’en-tête devrait respecter les spécifications; elle varie d’une région à l’autre
webrequest.Headers.Add("origin", "nom de l’origine");
webrequest.Headers.Add("country", "code de pays");
webrequest.Headers.Add("message", "type de message");
webrequest.Headers.Add("region", "nom de la région");
webrequest.Headers.Add("MerchNbr", "numéro d’établis. de 10 chiffres"); - fournir par Amex
webrequest.Headers.Add("RtInd", "code de routage");
webrequest.ContentType = "texte/xml";
return webrequest;
}//Fin de la session sécurisée CreateWebRequest
private void BuildReqStream(ref HttpWebRequest webrequest)
{
string strPost;
strPost = "AuthorizationRequestParam=actual message string";
StreamWriter myWriter = null;
strPost=Request; - This is were the auth message needs to be sent.
webrequest.ContentLength = strPost.Length;
try
{
myWriter = new StreamWriter(webrequest.GetRequestStream());
myWriter.Write(strPost);
}
20
}
finally
{
myWriter.Close();
}
POS020052 (0903070)
7 mai 2009
9.0
Marche à suivre pour créer un client test en C++
•
Créez un client C++ à l’aide de Visual Studio 2005.
•
Voir les exemples des méthodes Connect et Send aux pages suivantes.
7 mai 2009
POS020052 (0903070)
21
9.1
Exemple d’un client C++ — Méthode Connect
/////////////////////////////////////////////////////////////////////////////////////////////
//Méthode : Connect
//Objet :
La méthode Connect exige deux variables : HostAddress et Port
/////////////////////////////////////////////////////////////////////////////////////////////
bool XHttpConnection::Connect(const char *ptHostAddress, unsigned short nHostPort,
const char *ptUser, const char *ptPassword, bool bSecure)
{
DWORD dwFlags = 0;
if (m_pxInternetSession == NULL)
{
if (Initialize() == false)
{
return false;
}
}
try
{
if (bSecure)
{
dwFlags = INTERNET_FLAG_SECURE;
}
m_pxHttpConnection = m_pxInternetSession->GetHttpConnection(ptHostAddress, dwFlags,
nHostPort,ptUser,ptPassword);
}
catch(CInternetException *pIntEx)
{
TCHAR szCause[255];
pIntEx->GetErrorMessage(szCause,255);
//Journal
g_Log.PutEntry( (LPSTR)(LPCTSTR)theEdglibApp.GetTaskName(), //inscrire au journal CInternetException
"XHttpConnection::Connect", HTTP_EXCEPTION,
TRACING_ELMNT_EDGLIB,
EDGLIB_RECORDING_SOURCE_SOCKETS,
"%s", szCause) ;
return false;
}
return true;
}
22
POS020052 (0903070)
7 mai 2009
9.2
Exemple d’un client C++ — Méthode Send
////////////////////////////////////////////////////////////////////////////////////////////
//Méthode :
Send
//Objet :
transmettre des données au système
//Variables :
//
ptMessage – Message à envoyer
//
ptHeaders – En-têtes à ajouter (exemple Accept:text/*\r\n) //
DEVRAIT inclure tous les en-têtes
//
ptVerb – POST/GET
//
ptObjectName – Destinataire ??CardAuthorization.do
//
ptHttpVersion
///////////////////////////////////////////////////////////////////////////////////////////
int XHttpConnection::Send(CString* ptMessage, CString *ptHeaders, int iVerb, CString *ptObjectName,
CString ptHttpVersion, DWORD *pStatusCode)
{
try
{
m_pxFile = m_pxHttpConnection->OpenRequest(iVerb, //Verbe
(LPCTSTR) ptObjectName, //Objet ciblé - ?? whatever .do ?? CardAuthorization.do
NULL,
//(LPCTSTR) ptHeaders, PAS CERTAIN QU’IL S’AGISSE DES EN-TÊTES
1,
//toujours utiliser 1 comme contexte, il s’agit d’une session enfant
NULL,
//si la demande correspond à null, seul le texte est accepté
(LPCTSTR) ptHttpVersion, //version HTTP, HTTP/1.0 par défaut, Amex demande HTTP/1.1
INTERNET_FLAG_RELOAD ¦ INTERNET_FLAG_SECURE); //antémémoire, HTTPS
m_pxFile->AddRequestHeaders((LPCTSTR) ptHeaders);
DWORD iSize = ptMessage->GetLength();
//En-têtes déroutants, possible de les inscrire dans OpenRequest, AddRequestHeaders et SendRequest
BOOL bOK = m_pxFile->SendRequest(NULL,0,(LPVOID) ptMessage, iSize);
if (bOK)
{
m_pxFile->QueryInfoStatusCode(*pStatusCode);
}
else
{
*pStatusCode = 0;
}
return (int) iSize;
}
catch(CInternetException *pxIntEx)
{
TCHAR szCause[255];
pxIntEx->GetErrorMessage(szCause,255);
g_Log.PutEntry( (LPSTR)(LPCTSTR)theEdglibApp.GetTaskName(), //consigne le CInternetException
"XHttpConnection::Send", HTTP_EXCEPTION,
TRACING_ELMNT_EDGLIB,
EDGLIB_RECORDING_SOURCE_SOCKETS,
"%s", szCause) ;
Disconnect();
return -1;
}
}
7 mai 2009
POS020052 (0903070)
23
24
POS020052 (0903070)
7 mai 2009
10.0
•
Refus, erreurs et pannes
Pannes entraînées par le dépassement du temps imparti – Le temps requis pour traiter un
message peut parfois dépasser le temps imparti. Dans ces cas, un message d’erreur s’affiche à
l’écran du terminal ou de l’ordinateur. De plus, les pannes associées à un problème de transmission
ou de système n’ayant aucun lien avec le contenu du message sont classées dans la présente
catégorie de pannes. Aucune description supplémentaire n’est fournie pour ce type d’erreur.
Le temps imparti par la passerelle de paiement IP – Services Web d’American Express est
de 30 secondes (ainsi, après 30 secondes, American Express ferme la connexion et envoie une
réponse « null » au marchand ou au fournisseur, précisant le code d’état « 200 »).
•
Rejet du message de demande ou erreurs dans celui-ci – American Express retourne un message
de réponse précisant des code d’état et (ou) d’erreur qui expliquent pourquoi un message de
demande a été refusé ou rejeté.
Si les systèmes internes d’American Express sont incapables d’analyser le message ou si ce dernier
ne respecte pas le format exigé, une chaîne vierge (" "), sans code d’état, est retournée en réponse.
7 mai 2009
POS020052 (0903070)
25
26
POS020052 (0903070)
7 mai 2009
11.0
Codes de pays et de région
Le tableau ci-dessous dresse la liste des codes de pays et de région utilisés par American Express. Il
précise le nom du pays ou de l’entité avec le code de pays ISO et le code de région American Express
correspondant. Veuillez noter que les codes de pays en lettres (et sur fond gris) ne sont fournis qu’à
titre de référence et ne doivent pas être utilisés. Seuls les codes de pays en chiffres et les codes de
région en lettres peuvent être utilisés dans les dispositions de fichier décrites dans les présentes
spécifications.
Code de pays
Nom de pays ou d’entité
Afghanistan
Afrique du Sud
Albanie
Algérie
Allemagne, République d’
Andorre
Angola (UNITA)
Anguilla
Antigua et Barbuda
Antilles néerlandaises
Arabie Saoudite
Argentine
Arménie
Aruba
Australie
Autriche
Azerbaïdjan
Bahamas
Bahreïn
Bangladesh
Barbade
Belgique
Belize
Bénin
Bermudes
Bhoutan
Biélorussie
Bolivie
Bosnie-Herzégovine
Botswana
Brésil
Brunéi Darussalam
Bulgarie
Burkina Faso
7 mai 2009
Région
Chiffres
Lettres
Lettres
004
710
008
012
276
020
024
660
028
530
682
032
051
533
036
040
031
044
048
050
052
056
084
204
060
064
112
068
070
072
076
096
100
854
AFG
ZAF
ALB
DZA
DEU
AND
AGO
AIA
ATG
ANT
SAU
ARG
ARM
ABW
AUS
AUT
AZE
BHS
BHR
BGD
BRB
BEL
BLZ
BEN
BMU
BTN
BLR
BOL
BIH
BWA
BRA
BRN
BGR
BFA
LAC
LAC
LAC
LAC
LAC
JAPA
LAC
JAPA
LAC
LAC
LAC
LAC
JAPA
-
POS020052 (0903070)
27
Code de pays
Burundi
Cambodge
Cameroun
Canada
Cap-Vert
Chili
Chine
Chypre
Cité du Vatican (Saint-Siège)
Colombie
Comores
Congo, République démocratique du
Congo, République du
Corée, République de
Corée, République populaire démocratique de
Costa Rica
Côte d’Ivoire
Croatie, République de
Cuba
Danemark
Djibouti
Dominique
Égypte
El Salvador
Émirats arabes unis
Équateur
Erythrée
Espagne
Estonie
États-Unis
Éthiopie
Fidji
Finlande
France
Gabon
Gambie
Géorgie
Ghana
Gibraltar
Grèce
Grenade
Groenland
Guadeloupe
Guam
Guatemala
28
Région
Chiffres
Lettres
Lettres
108
116
120
124
132
152
156
196
336
170
174
180
178
410
408
188
384
191
192
208
262
212
818
222
784
218
232
724
233
840
231
242
246
250
266
270
268
288
292
300
308
304
312
316
320
BDI
KHM
CMR
CAN
CPV
CHL
CHN
CYP
VAT
COL
COM
COD
COG
KOR
PRK
CRI
CIV
HRV
CUB
DNK
DJI
DMA
EGY
SLV
ARE
ECU
ERI
ESP
EST
USA
ETH
FJI
FIN
FRA
GAB
GMB
GEO
GHA
GIB
GRC
GRD
GRL
GLP
GUM
GTM
JAPA
CAN
JAPA
LAC
USA
LAC
-
POS020052 (0903070)
7 mai 2009
Code de pays
Guinée
Guinée équatoriale
Guinée française
Guinée-Bissau
Guyana
Haïti
Honduras
Hong Kong
Hongrie
Île Bouvet
Île Christmas
Île Norfolk
Îles Caïmans
Îles Coco (anciennement Keeling)
Îles Cook
Îles Féroé
Îles Heard et McDonald
Îles Malouines
Îles Marianne du Nord
Îles Marshall
Îles Salomon
Îles Svalbard et Jan Mayen
Îles Turks et Caicos
Îles vierges américaines
Îles vierges britanniques
Îles Wallis et Futuna
Inde
Indonésie
Iran, République islamique d’
Iraq
Irlande
Islande
Israël
Italie
Jamahiriya arabe lybienne
Jamaïque
Japon
Jordanie
Kazakhstan
Kenya
Kirghizistan
Kiribati
Koweït
Lesotho
Lettonie
7 mai 2009
Région
Chiffres
Lettres
Lettres
324
226
254
624
328
332
340
344
348
074
162
574
136
166
184
234
334
238
580
584
090
744
796
850
092
876
356
360
364
368
372
352
376
380
434
388
392
400
398
404
417
296
414
426
428
GIN
GNQ
GUF
GNB
GUY
HTI
HND
HKG
HUN
BVT
CXR
NFK
CYM
CCK
COK
FRO
HMD
FLK
MNP
MHL
SLB
SJM
TCA
VIR
VGB
WLF
IND
IDN
IRN
IRQ
IRL
ISL
ISR
ITA
LBY
JAM
JPN
JOR
KAZ
KEN
KGZ
KIR
KWT
LSO
LVA
LAC
LAC
JAPA
JAPA
LAC
LAC
LAC
LAC
JAPA
EMEA
LAC
JAPA
-
POS020052 (0903070)
29
Code de pays
Région
Chiffres
Lettres
Lettres
Liban
Libéria
Liechtenstein
Lituanie
Luxembourg
Macao
Macédoine
Madagascar
Malaisie
Malawi
Maldives
Mali
Malte
Maroc
Martinique
Maurice
Mauritanie
Mayotte
Mexique
Micronésie, États fédérés de
Moldavie, République de la
Monaco
Mongolie
Monténégro
Montserrat
Mozambique
Myanmar
Namibie
Nauru
Népal
Nicaragua
Niger
Nigeria
Niue
Norvège
Nouvelle-Calédonie
Nouvelle-Zélande
Oman
Ouganda
Ouzbékistan
Pakistan
Palaos
Panama
Papouasie-Nouvelle-Guinée
Paraguay
422
430
438
440
442
446
807
450
458
454
462
466
470
504
474
480
478
175
484
583
498
492
496
499
500
508
104
516
520
524
558
562
566
570
578
540
554
512
800
860
586
585
591
598
600
LBN
LBR
LIE
LTU
LUX
MAC
MKD
MDG
MYS
MWI
MDV
MLI
MLT
MAR
MTQ
MUS
MRT
MYT
MEX
FSM
MDA
MCO
MNG
MNE
MSR
MOZ
MMR
NAM
NRU
NPL
NIC
NER
NGA
NIU
NOR
NCL
NZL
OMN
UGA
UZB
PAK
PLW
PAN
PNG
PRY
JAPA
LAC
JAPA
LAC
JAPA
JAPA
LAC
LAC
30
POS020052 (0903070)
7 mai 2009
Code de pays
Pays-Bas
Pérou
Petites îles avoisinant les États-Unis
Philippines
Pitcairn
Pologne
Polynésie française
Portugal
Puerto Rico
Qatar
République arabe syrienne
République centrafricaine
République dominicaine
République populaire démocratique lao
République tchèque
Réunion
Roumanie
Royaume-Uni
Russie, Fédération de
Rwanda
Sahara occidental
Saint-Barthélemy
Sainte-Hélène
Sainte-Lucie
Saint-Kitts-et-Nevis
Saint-Marin
Saint-Martin
Saint-Pierre-et-Miquelon
Saint-Vincent et les Grenadines
Samoa
Samoa américaines
Sao Tomé-et-Principe
Sénégal
Serbie
Seychelles
Sierra Leone
Singapour
Slovaquie
Slovénie
Somalie
Soudan
Sri Lanka
Suède
Suisse
Suriname
7 mai 2009
Région
Chiffres
Lettres
Lettres
528
604
581
608
612
616
258
620
630
634
760
140
214
418
203
638
642
826
643
646
732
652
654
662
659
674
663
666
670
882
016
678
686
688
690
694
702
703
705
706
736
144
752
756
740
NLD
PER
UMI
PHL
PCN
POL
PYF
PRT
PRI
QAT
SYR
CAF
DOM
LAO
CZE
REU
ROU
GBR
RUS
RWA
ESH
BLM
SHN
LCA
KNA
SMR
MAF
SPM
VCT
WSM
ASM
STP
SEN
RSD
SYC
SLE
SGP
SVK
SVN
SOM
SDN
LKA
SWE
CHE
SUR
LAC
EMEA
LAC
LAC
LAC
LAC
LAC
JAPA
LAC
POS020052 (0903070)
31
Code de pays
Swaziland
Tadjikistan
Taïwan
Tanzanie, République-Unie de
Tchad
Terres australes françaises
Territoire britannique de l’océan Indien
Thaïlande
Timor-Leste
Togo
Tokelau
Tonga
Trinité-et-Tobago
Tunisie
Turkménistan
Turquie
Tuvalu
Ukraine
Uruguay
Vanuatu
Venezuela
Vietnam
Yémen
Zambie
Zimbabwe
32
Région
Chiffres
Lettres
Lettres
748
762
158
834
148
260
086
764
626
768
772
776
780
788
795
792
798
804
858
548
862
704
887
894
716
SWZ
TJK
TWN
TZA
TCD
ATF
IOT
THA
TLS
TGO
TKL
TON
TTO
TUN
TKM
TUR
TUV
UKR
URY
VUT
VEN
VNM
YEM
ZMB
ZWE
JAPA
JAPA
LAC
-
POS020052 (0903070)
7 mai 2009

AMEX Web Services IP Payments HTTPS Comm Guide

Transcription

Documents pareils

Perte de vos cartes et chèques bancaires

BAROMETRE SERVICES CLIENTS AMERICAN EXPRESS 2012

Tombola American Express Shoppingtrip à New York RÈGLEMENT

L`Extension de Garantie

Carte Green American Express Découvrez le monde American

«Un photographe pro- fessionnel met votre entreprise parfaitement

formulaire de reclamation

Carte AMERICAN EXPRESS GOLD

Christophe BARBIER Ancien élève de l`Ecole Normale Supérieure