Gestion des réponses

Vue d'ensemble

Durant le développement, Moneris fournit les systèmes de simulateur pour tester votre solution et s’assurer que vos applications et systèmes soient prêts à gérer les réponses de transaction. Gérer une réponse de l’API de Moneris comprend la confirmation de l’état de la requête et la création de la logique au sein de votre solution afin de prendre les mesures adéquates. Dans certains scénarios, il faut utiliser une valeur dans le corps de la réponse pour indiquer la prochaine transaction à effectuer. Pour les transactions échouées, cela peut vouloir dire d’incorporer les erreurs documentées afin de prévenir les transactions réessayées ou d’inviter les titulaires de carte à utiliser un autre mode de paiement.

Niveaux de réponses

Dans une transaction typique, le processus de communication passe à travers plusieurs systèmes. Le diagramme ci-dessous fournit un abrégé pour comprendre les points de défaillance possibles dans votre transaction afin d’aider au développement et au dépannage. Nous utiliserons le terme « Niveaux de réponses » pour nommer toutes les zones du diagramme et discuter des problèmes possibles de cette interface.

📘

Systèmes tiers en tant que niveau 0.5 ou 1.5

Certaines intégrations de commerçant peuvent utiliser un fournisseur tiers ou d’intergiciels qui agit entre les niveaux du diagramme. Elles peuvent être entre :

• le serveur du commerçant et Moneris, habituellement en tant qu’intégration de paiement préintégrée;

• le titulaire de carte et le serveur du commerçant (notamment un module de panier d’achats préintégré pour un commerce électronique). Si votre solution comprend l’une de ces intégrations, gardez cette couche additionnelle en tête lors de la conception de votre gestion des réponses.

Niveau 1 : Du titulaire de carte au commerçant

Les erreurs générées à cette étape surviennent avant qu’une requête de l’API de Moneris ne soit envoyée et sont liées à votre ’implémentation commerçant. Elles peuvent être associées, ou non, au paiement, selon la validation des données effectuée par votre solution. Les messages d’erreur générés à ce niveau et le processus pour corriger les erreurs associées seront différents pour chaque système de commerçant et à l’extérieur de la portée de cette page, mais nous suggérons que tout message d’erreur produit soit convivial pour le titulaire de carte.

Niveau 2 : Du commerçant à Passerelle Moneris

Les erreurs générées à cette étape se produisent lorsque votre serveur envoie un message de requête et reçoit une réponse qui indique un échec ou aucune réponse.

Réponse échouée

La nature du traitement des transactions comprend la possibilité d’erreurs de formatage ou de contenu dans votre message de requête ou d’erreurs de communication en aval des endpoints (points de terminaison) de l’API de Moneris qui ne peuvent pas être évitées. Par conséquent, votre application de paiement doit gérer correctement toutes les réponses qui en découlent et qui indiquent une erreur.

L’API de Moneris utilise les codes d’état HTTP standards et un Problem JSON dans chaque erreur de réponse pour aider à réparer la nature de l’erreur. Les champs du corps de la réponse peuvent fournir des liens vers le contenu de l’erreur et des détails sur la nature de cette occurrence de l’erreur, en plus de faire la liste des champs liés à cette erreur.

{
"type": "https://developer.moneris.com/en/More/Testing/Response%20Codes",
"title": "FORBIDDEN_REQUEST",
"status": 403,
"detail": null,
"instance": null,
"category": "UNAUTHORIZED_ERROR",
"errors": [ ]
}

📘

Les codes d’état HTTP officiels sont définis conformément aux normes RFC et enregistrés dans :

le registre des codes d’état de l’IANA (disponible en anglais seulement)

Les principales normes RFC sont :

• RFC7231 - HTTP/1.1: Semantics (or RFC7235 - HTTP/1.1: Authentication)
• RFC 6585 - HTTP: Additional Status Codes

De plus, Moneris utilise des objets Problem JSON pour chaque RFC 7807 dans les réponses d’erreur pour les erreurs d’utilisation du client (codes d’état 4xx) et erreurs de traitement du côté du serveur (codes d’état 5xx).

No Response / Timed Out (Aucune réponse ou expiration du système)

Si vous ne recevez pas une réponse, cela indique qu’il y a un problème de connexion réseau entre votre serveur de commerçant et Moneris.

• Confirmez que l’URL utilisée pour la requête est valide dans notre matériel. Les erreurs dans le domaine peuvent causer des problèmes de délai d’attente.

• Confirmez que l’URL utilisée pour la requête est valide dans notre matériel. Les erreurs dans le domaine peuvent causer des problèmes de délai d’attente.

Niveau 3 : De Moneris aux marques de carte et émetteurs

Certaines requêtes de l’API de Moneris peuvent revenir avec succès, mais nécessitent une gestion des réponses additionnelle qui va plus loin que le code d’état HTTP. Habituellement, des champs particuliers sont inclus dans le corps de la réponse afin d’indiquer l’état de l’entité ou d’éclairer les décisions d’affaires prises par votre application. Ces éléments sont à l’extérieur de la portée de l’état HTTP ou représentent des microservices en aval dans le processus de paiement, qui retournent leurs réponses dans le cadre de la transaction générale.

📘

Requête POST partielle de création de paiement

JSON

	"paymentStatus": "SUCCEEDED",
	"transactionDetails": {
	"transactionUniqueId": "string",
	"isoResponseCode": 1,
	"responseCode": 1,
	"message": "approved",
	"ecommerceIndicator": "AUTHENTICATED_ECOMMERCE"
},

Pour un exemple de base, nous pouvons regarder la réponse pour une entité de paiement :

• La variable “paymentStatus” donne l’état actuel du paiement. Les états possibles sont dans la liste de Référence API, notamment :

  • la variable “DECLINED _RETRY” requête de retenter la transaction de paiement immédiatement;

  • la variable “DECLINED” avise que la transaction a été rejetée par notre serveur, la marque de carte ou la banque émettrice;

  • la variable “CANCELED” indique que le paiement a été annulé par l’entremise de l’endpoint (point de terminaison) POST d’annulation du paiement;

  • la variable “CANCELED” indique que le paiement a été annulé par l’entremise de l’endpoint (point de terminaison) POST d’annulation du paiement;

  • la variable “SUCCEEDED” est l’état d’un paiement approuvé, que ce soit avec la requête POST de conclusion du paiement OU pour un achat effectué par l’entremise de la requête POST de création de paiement avec la variable “automaticCapture” de “true”.

  • la variable “PROCESSING” revient dans toute réponse d'un processus asynchrone en cours.

• La variable “transactionDetails” comprend des renseignements utiles pour dépanner les transactions refusées, comme le « message » du terminal pour la réponse, ainsi que les variables “isoResponseCode” et “responseCode”. Celles-ci offrent plus de contexte sur les refus des émetteurs lors des enquêtes sur les transactions refusées.

📘

Codes ISO et de réponse du serveur

Pour les endpoints (points de terminaison) de paiement, Moneris suggère l’utilisation des valeurs possibles de la variable “paymentStatus” en tant que scénarios de test habituels. Si vous avez besoin de plus de renseignements de la transaction, vous pouvez aussi reproduire les différentes valeurs “responseCode” du serveur au moyen de notre Simulateur de valeur des cents dans l’environnement de tests. Durant la phase de tests, la valeur de cents de votre transaction (1,xx $) détermine le succès ou l’échec de votre paiement. Consultez le tableau des valeurs des cents et les tableaux des codes du serveur et de réponse ISO pour en savoir plus.

Tableaux des codes de réponse

📘

Gestion des reçus

Après la gestion de la réponse, vous pourriez avoir à fournir des renseignements de la réponse afin de créer un reçu pour le client. Les reçus suivent obligatoirement les règles des associations de cartes en produisant des reçus pour les titulaires de carte.

Codes d’état HTTP

Codes de réussite

Ces codes sont renvoyés lorsque la requête est reçue avec succès, comprise et acceptée.

Codes de redirection

Ces codes sont renvoyés lorsque votre requête échoue et que votre client doit prendre d’autres mesures pour conclure la requête.

Codes d’erreur du client

Ces codes sont renvoyés lorsque votre requête échoue en raison d’erreurs possibles dans le message de la requête.

Codes d’erreur du serveur

Ces codes sont renvoyés lorsque votre requête échoue en raison de problèmes ou d’erreurs du serveur.