Intégration avec PostFinance DirectLink (serveur à serveur)
1. Introduction
PostFinance DirectLink vous permet d’établir des liens entre vos applications et notre système, comme si notre système était tout simplement un serveur local. Cela fournit un accès programme à programme (serveur à serveur) entre le logiciel du marchand et nos fonctions de paiement et d’administration. Le programme du marchand interagit directement avec notre API à distance, sans intervention humaine.
Le graphique ci-dessus représente une transaction avec DirectLink
| En utilisant DirectLink, il n’y a aucun contact entre notre système et le client de notre marchand. Le marchand transmet toutes les informations requises pour effectuer directement le paiement à partir de notre système dans une requête HTTPS POST. Notre système demande la transaction financière (de manière synchrone ou asynchrone) à l’acquéreur pertinent et retourne la réponse au marchand dans un format XML. Le programme du marchand lit la réponse et reprend le traitement. Le marchand est donc responsable pour la collecte et le stockage des détails confidentiels de paiement de son client. Il doit garantir la confidentialité et la sécurité de ces détails via l’utilisation de communication web encryptée et d’un serveur de sécurité. |
Le marchand peut effectuer des nouvelles commandes, des maintenances sur des commandes existantes et des interrogations sur le statut d’une commande en particulier en utilisant DirectLink.
L’usage de requêtes automatisées en DirectLink par le marchand ne l’empêche pas de consulter manuellement l’historique des transactions dans son module de gestion, en utilisant son navigateur internet ou un téléchargement de rapport. Pour la configuration et le fonctionnement du site d’administration, veuillez vous référer au Utilisez votre compte PostFinance / Consultez vos transactions.
2. Procédures générales et paramètres de sécurité
Les procédures générales et contrôles de sécurité sont valides pour toutes les demandes DirectLink: nouvelles requêtes de commande, requêtes de maintenance et interrogations directes (direct queries).
Le graphique ci-dessus représente les différentes étapes d’une transaction avec DirectLink
2.1 Utilisateur API
Un utilisateur API (Application Program Interface) est nécessaire pour présenter des demandes DirectLink.En général, cet utilisateur est spécifiquement conçu pour qu’une application puisse présenter des demandes automatiques à la plateforme de paiement.
Vous pouvez créer un utilisateur API dans votre compte Ingenico via « Configuration » > « Users » (Utilisateurs). Sélectionnez « New User » (Nouvel utilisateur) et remplissez les champs obligatoires.
Pour que le nouvel utilisateur soit un utilisateur API, assurez-vous de cocher la case « Special user for API (no access to admin.) » (Utilisateur spécial API (aucun accès admin.)).
|
Bien que plusieurs profils d’utilisateur soient disponibles pour l’utilisateur API, nous vous recommandons vivement de configurer cet utilisateur sur le profil « Admin » (Administrateur). Le mot de passe d’un utilisateur API n’a pas besoin d’être modifié régulièrement. Ce qui est avantageux lorsque le mot de passe doit être codé en dur dans votre application. Nous vous recommandons néanmoins de changer de mot de passe de temps à autre. |
2.2 Formulaire de requête
Pour les requêtes de nouvelle commande, les requêtes de maintenance et les interrogations directes (direct queries), le marchand doit envoyer des requêtes avec certains paramètres vers des URLs spécifiques. Les paramètres de paiement/maintenance/interrogation doivent être envoyés dans une demande POST comme suit:
PSPID=value1&USERID=value2&PSWD=value3&…
Le sous-type (subtype) indiquant le type de média dans le champ header “Content-Type entity” dans la requête POST doit être encodé en "application/x-www-form-urlencoded".
DirectLink fonctionne dans un mode “une requête-une réponse”, chaque paiement est traité individuellement. Notre système gère individuellement les requêtes de transaction via DirectLink et peut travailler simultanément (lorsque cette option est supportée techniquement), par exemple nous attendons la réponse de la banque avant de renvoyer une réponse XLM vers la requête.
2.3 Sécurité
Lorsque nous recevons des requêtes sur nos serveurs, nous vérifions le niveau de cryptage ainsi que l’adresse IP à partir de laquelle la requête a été envoyée.
2.3.1 Cryptage
DirectLink est construit sur un protocole de communication sécurisé et robuste. L’API DirectLink est un ensemble d’instructions soumises avec des requêtes HTTPS POST classiques. Nous permettons aux marchands de se connecter à nous dans un seul mode https sécurisé.Il n’est pas nécessaire d’utiliser un certificat client TLS.
2.3.2 Signature SHA
La signature SHA est basée sur le principe même que le serveur du marchand génère une chaîne unique de caractères pour chaque commande, hachée avec les algorythmes SHA-1, SHA-256 u SHA-512. Le résultat de ce hachage nous est envoyé dans la requête de commande du marchand. Notre système reconstruit la signature afin de vérifier l’intégrité des données de commande qui nous ont été envoyées dans la requête.
Cette chaîne est construite en concaténant les valeurs des champs envoyés avec la commande (triés alphabétiquement, dans le format ‘paramètre=valeur’), avec chaque paramètre et valeur suivis d’une passphrase. La passphrase est définie dans l’Information Technique du marchand, dans l’onglet “Contrôle de données et origine”, dans la section “Contrôles pour DirectLink”. Pour la liste complete des paramètres à inclure dans le Digest SHA, veuillez cliquer ici. A noter que ces valeurs sont toutes sensibles à la casse lorsqu’elles sont assemblées pour former la chaîne avant le hachage!
Important
|
Lorsque vous hachez la suite (string) composé par l’algorythme SHA, un résumé hexadécimal sera renvoyé. La longueur de ce résumé SHA est de 40 caractères pour le SHA-1, 64 pour le SHA-256 et 128 pour le SHA-512. Ce résultat devrait être envoyé à notre système dans votre requête de commande, en utilisant le champ “SHASign”.
Notre système recomposera lui-même la suite (string) SHA en se basant sur les paramètres reçus et comparera le résumé (digest) du marchand avec le résumé (digest) que nous avons généré. Si le résultat n’est pas identique, la commande sera refuse. Ce contrôle garantit l’exactitude et l’intégrité des données de commande.
Vous pouvez tester votre signature SHA ici.
| Exemple de calcul d’un SHA-1-IN avec les seuls paramètres de base Paramètres (par ordre alphabétique) AMOUNT: 15.00 -> 1500 CARDNO: 4111111111111111 CURRENCY: EUR OPERATION: RES ORDERID: 1234 PSPID: MyPSPID SHA Passphrase (Dans "Information Technique"): Mysecretsig1875!? String à hacher AMOUNT=1500Mysecretsig1875!?CARDNO=4111111111111111Mysecretsig1875!?CURRENCY=EURMysecretsig1875!? OPERATION=RESMysecretsig1875!?ORDERID=1234Mysecretsig1875!?PSPID=MyPSPIDMysecretsig1875!? Résumé de résultat (SHA-1) 2B459D4D3AF0C678695AE77EE5BF0C83CA6F0AD8 |
Si le signature SHA envoyé dans votre requête ne correspond pas au SHASIGN que nous avons récupéré en utilisant les details de la commande ainsi que la passphrase entrée dans le champ Signature SHA-IN dans l’onglet “Contrôle de données et origine”, dans la section “Contrôles pour DirectLink” dans la page d’Information Technique, vous recevrez le message d’erreur “unknown order/1/s/".
Si le champ "SHASIGN" dans votre requête est vide, mais qu’une passphrase a été entrée dans le champ Signature SHA-IN dans l’onglet “Contrôle de données et origine”, dans la section “Contrôles pour DirectLink” dans la page d’Information Technique (indiquant ainsi que vous voulez utilise une signature SHA pour chaque transaction), vous recevrez le message d’erreur “unknown order/0/s/".
2.3.3 Adresse IP
Pour chaque requête, notre système vérifie l’adresse IP à partir de laquelle la requête a été envoyée afin de s’assurer que les requêtes ont bien été envoyées à partir du serveur du marchand. Dans le champ adresse IP de l’onglet "Contrôle de données et d’origine”, dans la section "Contrôles pour DirectLink" de la page Information technique de votre compte, vous devez entrer l’adresse IP ou le groupe d’adresse IP des serveurs qui envoient vos requêtes.
Si l’adresse IP à partir de laquelle la requête a été envoyée n’a pas été déclarée dans le champ d’adresse IP de l’onglet “Contrôle de données et origine”, à vérifier dans la section DirectLink de la page d’information technique de votre compte, vous recevrez le message d’erreur “unknown order/1/i”. L’adresse IP à partir de laquelle la requête a été envoyée sera également montrée dans le message d’erreur.
2.4 Parsing de la réponse
Nous retournerons une réponse XML à votre requête. Veuillez vous assurer que vos systèmes sont bien en mesure de faire du parsing en recevant la réponse XML de manière aussi tolérante que possible afin d’éviter tout problème dans le futur, par exemple éviter les noms d’attributs sensibles à la casse, ne pas convenir d’un ordre spécifique pour les attributs retournés dans les réponses, s’assurer que les nouveaux attributs dans la réponse ne causeront pas de problème, etc.
3. Effectuer une nouvelle commande
3.1 URL de requête
- L’URL de la requête dans l’environnement de TEST est https://e-payment.postfinance.ch/ncol/test/orderdirect.asp.
- L’URL de la requête dans l’environnement de PRODUCTION est https://e-payment.postfinance.ch/ncol/prod/orderdirect.asp.
|
Remplacer "test" par "prod" N’oubliez pas de remplacer “test” par “prod” dans l’URL de la requête lorsque vous passez à votre compte de PRODUCTION. Si vous oubliez de changer l’URL de requête, lorsque vous commencerez à traiter des commandes réelles, vos transactions seront envoyées vers l’environnement de test et ne seront pas envoyées vers les acquéreurs/banques. |
3.2 Paramètres de requête
Le tableau ci-dessous contient les paramètres de requête nécessaires à l’envoi d’une nouvelle commande:
| Champ | Usage |
|---|---|
| PSPID |
Votre nom d’affiliation dans notre système. Format: AN, 30 Obligatoire |
| ORDERID |
Votre numéro de commande unique (référence marchand). Format: AN, 40 Obligatoire |
| USERID |
Nom de votre utilisateur applicatif (API). Veuillez vous référer à la documentation User Manager pour plus d’informations sur comment créer un utilisateur API. Format: AN, 20 (min. 2) Obligatoire |
| PSWD |
Mot de passe de l’utilisateur API (USERID). Format: AN Obligatoire |
| AMOUNT |
Montant à payer MULTIPLIE PAR 100, puisque le format du montant ne doit pas contenir de décimales or tout type de séparateur. Format: N, 15 Obligatoire |
| CURRENCY |
Code devise de la commande en format ISO alpha, par exemple: EUR, USD, GBP, CHF, etc. Format: AN, 3 Obligatoire |
| CARDNO |
Numéro de Carte/Compte. Format: AN, 21 Obligatoire |
| ED |
Date d’expiration. Format: MM/AA ou MMAA Obligatoire |
| COM |
Description de la Commande. Format: AN, 100 Optionnel |
| CN |
Nom du client. Format: AN, 35 Obligatoire |
|
Adresse e-mail du client. Si vous faites une demande de 3DSv2.1, assurez-vous que le format d’email soit valide. Dans le cas contraire, l’authentification client forte utilisera le protocole 3DSv1.0. Format: AN, 50 Optionnel |
|
| SHASIGN |
Signature (suite (string) hachée) pour authentifier les données (cfr. SHA-IN Signature). Format: AN, 128 Optionnel |
| CVC |
Code de Vérification de la Carte (CVC - Card Verification Code). En fonction du type de carte, le code de vérification sera un code de 3 ou 4 chiffres, situé à l’avant ou à l’arrière de la carte, un numéro d’émission, une date de début ou une date de naissance. Format: N, 5 Obligatoire |
| ECOM_PAYMENT_ CARD_VERIFICATION |
Alternative au CVC: date de naissance / numéro d’émission / etc. (en function du pays/de la banque) Format: N, 5 Obligatoire |
| OWNERADDRESS |
Nom de rue et numéro du client. Format: AN, 50 Optionnel |
| OWNERZIP |
Code postal du client. Format: AN, 10 Optionnel |
| OWNERTOWN |
Nom de la ville du client. Format: AN, 40 Optionnel |
| OWNERCTY |
Pays du client, par exemple BE, NL, FR, etc. Format: AN, 2 Optionnel |
| OWNERTELNO |
Numéro de téléphone du client. Format: AN, 30 Optionnel |
| OPERATION |
Définit le type de transaction demandée. Vous pouvez configurer une opération par défaut (procédure de paiement) dans l’onglet "Paramètres de transaction globaux", section "Code d’opération par défaut" de la page d’Information technique. Lorsque vous envoyez une valeur d’opération dans la requête, celle-ci écrasera la valeur par défaut. Valeurs possibles:
Optionnel:
Format: AN, 3 Obligatoire |
| WITHROOT |
Ajoute un élément racine à votre réponse XML. Valeurs possibles: ‘Y’ ou vide. Format: Y ou <empty> Optionnel |
| REMOTE_ADDR |
Adresse IP du client (Seulement pour le module de détection de fraude (FDM). Si une vérification de pays ne doit pas être effectuée sur l’adresse IP, envoyez “NONE”. Format: AN Optionnel |
| RTIMEOUT |
Timeout de requête pour la transaction (en secondes, valeur entre 30 et 90) Format: N, 2 Optionnel |
| ECI |
Indicateur Electronique de Commerce (Electronic Commerce Indicator). Vous pouvez configurer une valeur ECI par défaut dans l’onglet “Paramètres de transaction globaux”, section “valeur ECI par défaut” de la page d’Information Technique. Lorsque vous envoyez une valeur ECI dans la requête, celle-ci écrasera la valeur ECI par défaut. Valeurs (numériques) possibles: Format: N, 2 Optionnel |
Si vous traitez des paiements récurrents, vous devez ajouter les paramètres Credentials-on-file (COF) à votre demande.
Consultez notre guide Alias Manager pour tout savoir sur le traitement des transactions COF.
La liste des paramètres possible à envoyer peut être plus longue pour les marchands qui ont actives certaines options/fonctionnalités dans leurs comptes. Veuillez vous référer à la documentation relative à chaque option pour plus d’informations concernant les paramètres additionnels liés à cette option.
Les paramètres de requêtes suivants sont obligatoires pour les nouvelles commandes:
- PSPID et USERID
- PSWD
- ORDERID
- AMOUNT (x 100)
- CURRENCY
- CARDNO
- ED
- CVC
- OPERATION
3.3 Page de test
Une page de test pour une nouvelle commande peut être trouvée à l’adresse: https://e-payment.postfinance.ch/ncol/test/testodl.asp.
3.4 Exclure les moyens de paiement spécifiques
Si vous désirez qu’un client ne soit pas en mesure de payer en utilisant un ou plusieurs moyens de paiement, vous pouvez utiliser un paramètre à cet effet.
Ceci est particulièrement utile pour les sous-types de carte, spécialement lorsque vous désirez accepter un type de carte (ex.: MasterCard), mais pas les sous-types qui lui sont associés (ex.: Maestro).
Le paramètre est le suivant:
| Champ | Usage |
|---|---|
| EXCLPMLIST | Liste des moyens de paiement et/ou types de carte de crédit qui ne doivent PAS être utilisés, séparés par un “;” (point virgule). |
Si un client essaie de payer avec une carte liée à un moyen de paiement et/ou un (sous) type de carte que vous avez exclu en utilisant le paramètre EXCLPMLIST, le message d’erreur “Card number incorrect or incompatible” (Numéro de carte incorrect ou incompatible) sera retourné dans le champ NCERRORPLUS.
3.5 Requête de commande utilisant 3-D Secure
Notre système supporte l’usage de 3-D Secure à travers DirectLink.
|
Important
|
3.6 Subdivision en cartes de crédit/débit
La fonctionnalité consistant à subdiviser VISA et MasterCard en méthodes de paiement par débit et par crédit vous permet de les offrir à vos clients sous deux formes (p. ex. VISA Debit et VISA Credit), mais vous pouvez aussi décider de n'accepter qu'une seule de ces deux formes de paiement.
Pour pouvoir utiliser cette fonctionnalité de subdivision en cartes de crédit et de débit via DirectLink, vous devez inclure le paramètre CREDITDEBIT dans les champs masqués que vous envoyez à la page de paiement (et les inclure également, par conséquent, dans le calcul SHA-IN !).
| Champ | Format |
|---|---|
| CREDITDEBIT | "C": credit card (carte de crédit) "D": debit card (carte de débit) |
Erreur liée : Si l'acheteur sélectionne la méthode par carte de débit, mais entre ensuite un numéro de carte de crédit, un code d'erreur est renvoyé : « Marque/mode de paiement incorrect ».
Si le paiement est traité avec succès avec le paramètre CREDITDEBIT, ce même paramètre est également renvoyé dans la réponse XML, et / ou peut être demandé avec une requête directe. Cependant, si les valeurs soumises sont C ou D, les valeurs de retour sont « CREDIT » ou « DEBIT ».
Vous trouverez également ces valeurs de retour dans la vue d'ensemble de la transaction via « View transactions » et « Financial history », ainsi que dans les rapports que vous pouvez télécharger ensuite.
|
Configuration au sein de votre compte La fonctionnalité de subdivision peut également être activée et configurée par méthode de paiement dans votre compte PostFinance. Accédez à Subdivision en cartes de crédit/débit pour plus d'informations. |
3.7 Traitement de transactions avec des identifiants enregistrés
Consultez notre guide Alias Manager pour tout savoir sur le traitement des transactions COF.
4. Réponse de commande
Notre serveur retourne une réponse XML à la requête:
| Exemple d’une réponse XML à une requête de commande <?xml version=”1.0”?> |
Le tableau ci-dessous contient une liste des attributs de tag de type ncresponse:
| Champ | Usage |
|---|---|
| ACCEPTANCE | Code de réception retourné par l’acquéreur. |
| amount | Montant de la commande (non multiplié par 100). |
| BRAND | Type de carte ou information pour d'autres moyens de paiement. |
| currency | Devise de la commande. |
| ECI | Indicateur Electronique de Commerce. |
| NCERROR | Code d’erreur. |
| NCERRORPLUS | Explication du code d’erreur. |
| NCSTATUS | Statut lié au code NCERROR |
| orderID | Votre référence de paiement. |
| PAYID | Référence de paiement dans notre système. |
| PM | Moyen de paiement. |
| STATUS | Statut de la transaction. (Statuts possibles) |
La liste des attributs peut être plus longue pour les marchands qui ont activés certaines options (par exemple, le module de détection de fraude) dans leurs comptes. Veuillez vous référer à la documentation relative à chaque option pour plus d’informations concernant les attributs de réponses additionnels liés à cette option.
4.1 Double requête (doublon)
Si vous effectuez une requête pour un orderID existant et ayant déjà été utilisé (et traité correctement), notre réponse XML contiendra le PAYID correspondant à l’orderID existant, la valeur ACCEPTANCE donnée par l’acquéreur lors du traitement précédent, le STATUS (statut) “0” ainsi que le NCERROR “50001113”.
5. Maintenance directe: Maintenance sur des commandes existantes
Une requête de maintenance directe envoyée de votre application vous permet de:
- effectuer automatiquement une saisie de données (paiement) d’une commande autorisée (plutôt que manuellement dans votre module de gestion (back-office))
- annuler une autorisation liée à une commande
- renouveler une autorisation liée à une commande
- rembourser une commande payée.
Les saisies de données, annulations d’autorisation et renouvellements d’autorisation sont réservés spécifiquement aux marchands qui ont configuré leur compte/requêtes pour effectuer des autorisations et des saisies de données en deux étapes.
5.1 Requête de maintenance
5.1.1 URL de requête
- l’URL de requête dans l’environnement de TEST est https://e-payment.postfinance.ch/ncol/test/maintenancedirect.asp.
- l’URL de requête dans l’environnement de PRODUCTION est https://e-payment.postfinance.ch/ncol/prod/maintenancedirect.asp.
|
Important N’oubliez pas de remplacer “test” par “prod” dans l’URL de la requête lorsque vous passez à votre compte de PRODUCTION. Si vous oubliez de changer l’URL de requête, lorsque vous commencerez à traiter des commandes réelles, vos transactions seront envoyées vers l’environnement de test et ne seront pas envoyées vers les acquéreurs/banques. |
5.1.2 Paramètres de requête
Le tableau ci-dessous comprend les paramètres de requête obligatoires afin d’effectuer une opération de maintenance:
| Champ | Usage |
|---|---|
| AMOUNT |
Montant de la commande multiplié par 100. Celui-ci est seulement obligatoire lorsque le montant de la maintenance diffère du montant de l’autorisation initiale. Cependant, nous recommandons son utilisation dans tous les cas. Notre système vérifiera que le montant de la transaction de maintenance n’est pas supérieur au montant de l’autorisation/du paiement. |
| OPERATION |
Valeurs possibles:
A noter que les opérations DEL et DES (annulations d’une autorisation) ne sont pas supportées par tous les acquéreurs, nous enverrons malgré tout une simulation d’annulation d’autorisation dans le module de gestion (back-office). |
| ORDERID | Vous pouvez envoyer le PAYID ou l’ORDERID afin d’identifier la commande originale. Nous recommandons l’utilisation du PAYID. |
| PAYID | |
| PSPID | PSPID de votre compte PostFinance |
| PSWD | Le mot de passe du USERID |
| SHASIGN | Calcul de hachage SHA, pour authentifier les données (cfr. Signature SHA-IN) |
| USERID | Utilisateur API |
5.2 Réponse de maintenance
Notre serveur retourne une réponse XML à la requête:
| Exemple d’une réponse XML à une requête de maintenance directe: <?xml version=”1.0”?> <ncresponse orderID=”99999” PAYID=”1111111” PAYIDSUB=”3” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS="91" amount="125" currency="EUR"/> |
Le tableau ci-dessous comprend les attributs de tag ncresponse:
| Champ | Usage |
|---|---|
| ACCEPTANCE | Code d’acceptance renvoyé par l’acquéreur |
| AMOUNT | Montant de la commande (non multiplié par 100) |
| CURRENCY | Devise de la commande |
| NCERROR | Code d’erreur |
| NCERRORPLUS | Explication du code d’erreur (NCERROR) |
| NCSTATUS | Statut lié au code NCERROR |
| ORDERID | Votre référence de commande |
| PAYID | Référence de paiement dans notre système |
| PAYIDSUB | L’ID de niveau dans l’historique des opérations de maintenance du PAYID |
| STATUS | Statut de la transaction (Statuts possibles) |
L’attribut de tag standard pour ncresponse sont identiques à ceux pour la réponse XML à une nouvelle commande, à l’exception de l’attribut additionnels PAYIDSUB.
5.3 Double requête (doublon)
Si la maintenance est demandée deux fois pour la même commande, la seconde demande sera théoriquement refusée avec une erreur “50001127” (cette commande n’est pas autorisée), parce que la transaction initiale approuvée aura déjà modifié le statut de la commande.
6. Requête Directe (Direct Query): demander le statut d’une commande
Une demande d’interrogation directe (direct query) à partir de votre application vous permet de demander le statut d’une commande automatiquement (plutôt que manuellement dans votre module de gestion (back-office)). Vous ne pouvez envoyer des interrogations qu’une à la fois, et ne recevrez qu’un nombre limité de données par rapport à cette commande.
Si vous désirez plus d’informations sur la commande, vous pouvez vérifier la transaction dans le module de gestion (back-office) ou effectuer un téléchargement de fichier automatique ou manuel (cf. Consultez vos transactions et guide d’intégration avancé Batch).
6.1 Demande de requête
6.1.1 URL de requête
- L’URL de requête dans l’environnement de TEST est https://e-payment.postfinance.ch/ncol/test/querydirect.asp
- L’URL de requête dans l’environnement de PRODUCTION est https://e-payment.postfinance.ch/ncol/prod/querydirect.asp
|
Important N’oubliez pas de remplacer “test” par “prod” dans l’URL de requête lorsque vous passez votre compte en PRODUCTION. |
6.1.2 Paramètres de requête
Le tableau ci-dessous comprend les paramètres de requête obligatoires pour effectuer une interrogation directe (direct query):
| Champ |
Usage |
|---|---|
| ORDERID |
Vous pouvez envoyer le PAYID ou l’ORDERID afin d’identifier la commande originale. Nous recommandons l’utilisation du PAYID. |
| PAYID |
|
| PAYIDSUB |
Vous pouvez indiquer l’ID de niveau d’historique si vous utilise le PAYID pour identifier la commande originale (optionnel). |
| PSPID |
PSPID de votre compte PostFinance |
| PSWD |
Mot de passe de votre utilisateur API |
| USERID |
Votre utilisateur API |
6.1.3 Page de test
Un exemple (page de test) d’une requête d’interrogation directe (‘) peut être trouvé à l’adresse: https://e-payment.postfinance.ch/ncol/test/testdq.asp.
6.2 Réponse de requête
Notre serveur renvoie une réponse XML à la requête:
|
Exemple d’une réponse XML response à une interrogation directe (direct query): <?xml version=”1.0”?><ncresponse orderID=”99999” PAYID=”1111111” PAYIDSUB=”3” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS="9" ECI=”7” amount="125" currency="EUR" PM="CreditCard" BRAND="VISA" CARDNO="XXXXXXXXXXXX1111" IP="212.33.102.55"/> |
Le tableau ci-dessous comprend une liste des attributs de tag “ncresponse”:
| Champ |
Usage |
|---|---|
| ACCEPTANCE | Code d’acceptance renvoyé par l’acquéreur |
| amount | Montant de la commande (non multiplié par 100) |
| BRAND | Type de carte ou information similaire pour d’autres moyens de paiement |
| CARDNO | Le numéro de carte de credit masqué |
| currency | Devise de la commande |
| ECI | Indicateur de Commerce Electronique (Electronic Commerce Indicator) |
| IP | Adresse IP du client, telle que détectée par notre système dans une intégration en mode 3 tiers, ou envoyée via une intégration en mode 2 tiers |
| NCERROR | Code d’erreur |
| NCERRORPLUS | Explication du code d’erreur |
| NCSTATUS | Statut lié au code NCERROR |
| orderID | Votre référence de commande |
| PAYID | Référence de paiement dans notre système |
| PAYIDSUB | L’ID de niveau dans l’historique des opérations de maintenance du PAYID |
| PM | Moyen de paiement |
| STATUS | Statut de la transaction |
Les paramètres du champ standards libellés ncresponse sont identiques à ceux pour la réponse XML à une nouvelle commande, à l’exception des attributs additionnels PAYIDSUB, CARDNO et IP.
La liste des paramètres peut être plus longue pour les marchands qui ont activé certaines options (par exemple le module de détection de fraude) dans leurs comptes. Veuillez vous référer à la documentation spécifique à l’option pour obtenir plus d’informations sur les paramètres de réponse additionnels liés à ces options.
6.2.1 Transactions traitées en e-Commerce
Si les transactions pour lesquelles vous désirez vérifier le statut ont été traitées en mode e-Commerce, vous recevrez également les attributs additionnels suivants (dans la mesure où vous aviez envoyé dès le départ ces champs dans la transaction e-Commerce).
| Champ |
Usage |
|---|---|
| complus* |
Une valeur que vous souhaitiez recevoir |
| (paramplus content)* |
Les paramètres que vous désiriez recevoir et leurs valeurs |
* Cf. Paramètres du retour d'information variable (documentation e-Commerce)
|
Exemple d’une réponse XML à une interrogation directe (direct query) pour une transaction e-Commerce <ncresponse orderID=”99999” PAYID=”1111111” PAYIDSUB=”3” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS="9" amount="125" currency="EUR" PM="CreditCard" BRAND="VISA" CARDNO="XXXXXXXXXXXX1111" IP="212.33.102.55" COMPLUS="123456789123456789123456789" SessionID="126548354" ShopperID="73541312"/> |
6.3 Statuts possibles de réponse
Le champ STATUS comprendra le statut de la transaction. (cf. Statuts possible).
Seul le statut ci-dessous est spécifiquement lié à la recherche (query) elle-même:
| Statut | NCERROR | NCSTATUS | Explication |
|---|---|---|---|
| 88 | La recherche (query) sur querydirect.asp a échoué |
6.4 Requête Directe comme sécurité
Les temps de réponse pour une requête de transaction DirectLink sont généralement de quelques secondes; certains acquéreurs peuvent, cependant, avoir des temps de réponse plus longs.
Si vous n’avez pas reçu une réponse de notre système après 30 secondes, vous pouvez envoyer une requête à querydirect.asp, demandant le statut de votre transaction la plus récente à orderdirect.asp. Si vous recevez une réponse immédiate contenant le statut non final pour la transaction, il se pourrait qu’il y ait des problèmes chez l’acquéreur.
Si vous n’avez pas reçu une réponse à cette interrogation directe (direct query) après 10 secondes, il se pourrait qu’il y ait des problèmes de notre côté. Vous pouvez répéter cette requête vers querydirect.asp toutes les 30 secondes jusqu’à ce que vous receviez une réponse dans les 10 secondes.
A noter que :
|
|
Important Afin de protéger notre système de surcharges non nécessaires, nous interdisons les contrôles préalables du système qui incluent l’envoi de fausses transactions ou d’interrogations (queries) systématiques, ainsi que les interrogations (queries) systématiques utilisées pour obtenir le retour d’information de transaction (transaction feedback) pour chaque transaction. |
7. Demande de politique de confidentialité à l’attention du responsable du traitement des données
En vertu des articles 12, 13 et 14 du RGPD, le responsable du traitement a l’obligation d’informer ses clients finaux du futur traitement de leurs données personnelles. Il indiquera le type de données personnelles utilisées pour une transaction spécifique (méthode de paiement sélectionnée, responsable du traitement des données, acquéreur, fraude, etc.). Le résultat doit être disponible et visible au moment de la collecte des données et le titulaire de la carte doit pouvoir le télécharger et l’imprimer. Conformément au RGPD, vous devez fournir ces informations à votre client avant qu’il ne valide sa transaction. Ces informations seront de préférence affichées sur la page de saisie des données de compte ou carte bancaire.La demande de politique de confidentialité ci-dessous vous permet de récupérer toutes les informations que vous devez indiquer à votre client sur nos services pour être en conformité avec le RGPD.
7.1 Demande de requête
7.1.1 Demande d'URL
• L’URL de demande dans l’environnement TEST est https://e-payment.postfinance.ch/ncol/test/privacy-policy.asp
Remplacer « test » par « prod »
7.1.2 Demande de Paramètres
Le tableau suivant contient les paramètres de demande obligatoires à envoyer à vos clients concernant l’utilisation de leurs informations à caractère personnel :
| Champ | Format |
Description |
| USERID | Chaîne |
Votre utilisateur API |
| PSWD | Chaîne |
Votre mode de passe utilisateur API |
| PSPID |
Chaîne |
PSPID de votre compte |
| BRAND | Chaîne (p. ex. Visa) |
Facultatif : marque du moyen de paiement |
| LANGUAGE | ISO 639-1 : codes à deux lettres (p. ex. FR) |
Facultatif : la langue souhaitée du texte à récupérer. |
7.1.3 Page de test
Vous pouvez tester des demandes de requête directes : https://e-payment.postfinance.ch/ncol/test/privacy-policy.asp
7.2 Réponse de requête
Ci-dessous figure la liste des éléments XML et des exemples de réponses XML obtenues pour différents résultats.
| Nom | Format | Description |
| Response | Complexe | Root node, always present |
| Response.Status | Chaîne, valeurs possibles : Success, SuccessWithWarnings, Error | Toujours présent |
| Response.Body | Complexe | Présent uniquement quand Response.Status = Success ou SuccessWithWarnings |
| Response.Body.Html | Chaîne / html | Vide si Response.Status = SuccessWithWarnings & Response.Warnings.Warning.Code = NoContent |
| Response.Errors | Complexe | Présent uniquement quand Response.Status = Error |
| Response.Errors.Error | Complexe | Peut se produire plusieurs fois à l’intérieur d’un nœud <Errors> |
| Response.Warnings | Complexe | Uniquement présent quand Response.Status = SuccessWithWarnings ou Error |
| Response.Warnings.Warning | Complexe | Se produit plusieurs fois dans un nœud <Warnings> |
| Response.Errors.Error.Code Response.Warnings.Warning.Code |
Chaîne, valeurs possibles : •À l’intérieur d’un nœud <Error> : non autorisé, InternalServerError •À l’intérieur d’un nœud <Warning> : NoContent |
Toujours présent à l’intérieur d’un nœud <Error> ou <Warning> |
| Response.Errors.Error.Message Response.Warnings.Warning.Message |
Chaîne | Facultatif |
Ci-dessous figurent deux exemples de réussite :
1. Exemple de réponse XML pour un succès avec avertissements. L’exemple est affiché si aucune information à caractère personnel ne doit être divulguée au client.
<?xml version="1.0" encoding="utf-8"?><Response>
<Status>SuccessWithWarnings</Status>
<Warnings>
<Warning>
<Code>NoContent</Code>
</Warning>
</Warnings>
<Body>
<Html/>
</Body>
</Response>2. Exemple de réponse XML pour un succès avec contenu. L’exemple est affiché en deux sections.
<?xml version="1.0" encoding="utf-8"?>
<Response>
<Status>Success</Status>
<Body>
<Html><![CDATA[<ul><li><h2>Title 1</h2><p>Content 1</p></li><li><h2>Title 2 (VISA, American Express)</h2><p>Content 2</p></li></ul>]]></Html>
</Body>
</Response>
8. Paiement sécurisé avec 3-D Secure
Pour des informations de nature générale sur 3-D Secure v2, consultez notre PSD2 guide.
Découvrez ici comment mettre 3-D Secure en place dans le processus de paiement de façon sûre.