Description des champs de données du message
Vue d'ensemble
L’annexe suivante contient des informations sur les valeurs possibles pour le champ modifier (modificateur), les champs action (action) ainsi qu’une description de tous les autres champs de data (données).
Modificateur
Le modificateur est une valeur spéciale envoyée au terminal pour initier un type de transaction unique. Le tableau ci-dessous contient la liste de toutes les valeurs de modificateur prises en charge.
| Modificateur | Description |
|---|---|
| CASH | Le modificateur CASH est utilisé pour déclencher une transaction de paiement en espèces. |
| CNP | Le modificateur CNP est utilisé pour les transactions carte non présente / MOTO (commande par courrier ou par téléphone). Cette valeur permet à l’utilisateur de saisir manuellement les détails de la carte dans le terminal. |
| SCAN | Le modificateur SCAN est utilisé pour lancer le lecteur de codes QR / codes-barres. |
Tous les modificateurs ne sont pas compatibles avec tous les types de transaction. Le tableau ci-dessous présente les modificateurs pris en charge pour chaque type de transaction (action).
| Action | Modificateur pris en charge |
|---|---|
| “purchase” (achat) | CNP, CASH, SCAN |
| “independentRefund” (remboursement indépendant) | CNP |
| “preAuth” (préautorisation) | CNP |
| “balanceInquiry” (consultation de solde) | CNP, SCAN |
| “cardVerification” (vérification de carte) | CNP |
| “getTrack” (obtenir la piste) | CNP |
Action
Toutes les transactions prises en charge dans l’application autonome sont également prises en charge en mode intégré.
| Action | Description |
|---|---|
| “purchase” (achat) | Cette action déclenche la séquence d’achat sur le terminal. |
| “refund” (remboursement) | Cette action déclenche la séquence de remboursement sur le terminal. |
| “independentRefund” (remboursement indépendant) | Cette action déclenche la séquence de remboursement indépendant sur le terminal. |
| “void” (annulation) | Cette action déclenche la séquence d’annulation (correction) sur le terminal. |
| “balanceInquiry” (consultation de solde) | Cette action déclenche la séquence de consultation de solde sur le terminal. |
| “preAuthorization” (préautorisation) | Cette action déclenche la séquence de préautorisation sur le terminal. |
| “completion” (finalisation) | Cette action déclenche la séquence de finalisation de préautorisation sur le terminal. |
| “sync” (synchroniser) | Cette action déclenche la séquence de synchronisation avec Moneris (initialisation) sur le terminal. |
| “reboot” (redémarrage) | Cette action déclenche la séquence de redémarrage sur le terminal. |
| “scan” (scanner) | Cette action déclenche la séque |
Champs de données
Le tableau ci-dessous présente une liste des champs de data (données) utilisés dans les messages de requête (Request) et de réponse (Response).
| Name | Longueur | Type | Description | Obligatoire |
|---|---|---|---|---|
| action | V50 | String (chaîne) | action (action) fait référence au type de transaction que le terminal doit exécuter. Pour plus de détails, voir action (action). | |
| apiToken | V50 | String (chaîne) | Chaîne alphanumérique unique attribuée par Moneris lors de l’activation du compte marchand. Pour trouver votre apiToken (jeton API), consultez les paramètres d’administration de votre boutique de test ou de production dans le Merchant Resource Center, aux URL suivantes : Test : https://esqa.moneris.com/mpg/ Production : https://www3.moneris.com/mpg/ | |
| apiVersion | V20 | String (chaîne) | Numéro de version de l’API Cloud de Moneris. Actuellement « 3.0 ». | |
| approvedAmount | V10 | String (chaîne) | Montant du paiement reçu / approuvé. La valeur doit être en cents. Par exemple, 10,50 $ doit être envoyé comme « 1050 ». | |
| authCode | V8 | String (chaîne) | Numéro d’autorisation provenant de l’hôte. | |
| balance | V10 | String (chaîne) | Solde sur la carte-cadeau ou carte de fidélité. La valeur est en cents. | |
| barcodeData | V2000 | String (chaîne) | Données scannées du code-barres. | |
barcodeType(request) format(response) | V50 | String (chaîne) | Liste des formats de codes-barres pris en charge pour le scan. Valeurs valides :
| |
| cardCode | F3 | String (chaîne) | Ce champ identifie le type/programme de carte et est utilisé par Moneris et le terminal pour associer les totaux de l’appareil aux totaux de l’hôte. | |
| cardNumber | V200 | String (chaîne) | Détails de la piste 2 décrits dans ISO 7813 ou saisie manuelle. | |
| cardStatus | V10 | String (chaîne) | À déterminer (TBD). | |
| cardType | V2 | String (chaîne) | Abréviation utilisée par Moneris pour désigner un réseau de paiement particulier utilisé lors d’une transaction. Valeurs valides :
| |
| cardName | V25 | String (chaîne) | Nom de la marque de carte associé au cardType (type de carte). Valeurs valides :
| |
| cashback | V10 | String (chaîne) | Dans la requête : L’ECR peut envoyer un montant de remise en argent (valeur $) qui remplacera l’écran d’invite de remise en argent et invitera plutôt le titulaire de la carte à confirmer le montant envoyé par l’ECR. Dans la réponse : Ce champ contiendra le montant de remise en argent saisi par le client au terminal. La valeur doit être en cents. Par exemple, 10,50 $ doit être envoyé comme « 1050 ». | |
| cloudTicket | V100 | String (chaîne) | Valeur de référence pour la requête de transaction unique. | |
| completed | V5 | String (chaîne) | completed (complété) fait référence au status (statut) global de la transaction. Deux valeurs :
| |
| customIdData | V50 | String (chaîne) | Le champ customIdData (données d’identifiant personnalisé) est destiné aux données de vente supplémentaires, telles qu’un numéro de facture ou de fidélité. Le champ n’est pas chiffré et ne doit pas être utilisé pour des données sensibles ou de titulaire de carte (p. ex. PAN, CVV2, etc.). | |
| cvc | V10 | String (chaîne) | Code de vérification de la carte. | |
| cvdResults | F2 | String (chaîne) | Indique si le chiffre de vérification du titulaire de carte (CVD) est présent et, le cas échéant, le résultat de la vérification CVD. Le nom de ce champ varie selon la marque de la carte :
Valeurs valides :
Remarque : pour UnionPay, aucune valeur n’est renvoyée dans la réponse. | |
| dataTimestamp | F19 | String (chaîne) | Date et heure de la requête/réponse. | |
| dccOptIn | F4 | String (chaîne) | Indique une transaction avec conversion dynamique de devise (DCC) avec adhésion. Si un titulaire choisit de payer en devise étrangère, le terminal renverra : « true ». | |
| displayMessage | V512 | String (chaîne) | Message personnalisé à afficher sur le terminal. | |
| dynamicDescriptor | V20 | String (chaîne) | Description définie par le commerçant envoyée pour chaque transaction, qui apparaîtra sur le relevé de carte de crédit. Selon l’émetteur, le relevé affichera généralement le descripteur dynamique ajouté au nom commercial existant séparé par « / ». La longueur combinée ne peut excéder 22 caractères. Exemple : Nom commercial existant : ABC Painting Descripteur dynamique : Booking 12345 Relevé : ABC Painting/Booking 1 | |
| ecrId | V50 | String (chaîne) | Identifiant unique pour l’ECR. | |
| fileData | TBD | String (chaîne) | À déterminer (TBD). | |
| fileFormat | V50 | String (chaîne) | Format du fichier contenant la signature à retourner. Valeurs valides :
| |
| formFactor | V50 | String (chaîne) | L’indicateur de facteur de forme (FFI), également appelé type d’appareil pour Mastercard, décrit la technologie de carte à puce utilisée pour effectuer un paiement. Exemples : cartes plastiques, porte-clés, modules SIM de téléphones mobiles, jetons USB. Retourné si fourni par la carte. | |
| gracePeriodRemaining | V2 | String (chaîne) | Toujours retourné lorsque le champ optionnel hashValueSecondary (valeur de hachage secondaire) est inclus dans la réponse. Présent après un changement de clés HMAC ou une installation d’application neuve. Indique le nombre de jours où deux valeurs HASH sont retournées. Le compteur commence après la première commande getHash suivant une injection de clés ou installation, selon le dernier événement. Valeurs valides : 0-99. | |
| hashValue | F64 | String (chaîne) | Hachage des données de la carte. | |
| idempotencyKey | V50 | String (chaîne) | Identifiant unique de transaction pour éviter les requêtes en double. Pour les requêtes idempotentes, action, totalAmount et idempotencyKey doivent être identiques à la transaction initiale. Prend en charge tous les caractères alphanumériques et spéciaux sauf les guillemets. | |
| installmentOptIn | V5 | String (chaîne) | Indique une transaction Installment by Visa avec adhésion. Si un titulaire sélectionne un plan de versements, le terminal renverra : « true ». | |
| iso | V2 | String (chaîne) | Code de réponse ISO. Réponse standardisée selon la norme ISO 8583. | |
| istConfigCode | V25 | String (chaîne) | Code de configuration d’intégration fourni par Moneris. | |
| linkId | V50 | String (chaîne) | ID utilisé pour regrouper les transactions liées. | |
| loadedAmount | V9 | String (chaîne) | Montant chargé sur la carte. | |
| maskedPan | V21 | String (chaîne) | Numéro de compte principal masqué. | |
| merchantId | V13 | String (chaîne) | ID du commerçant demandeur. | |
| modifier | V24 | String (chaîne) | Valeur spéciale envoyée au terminal pour initier un type de transaction unique. Pour plus de détails, voir modifier (modificateur). | |
| newHash | V5 | String (chaîne) | À déterminer (TBD). | |
| orderId | V50 | String (chaîne) | Identifiant de transaction défini par le commerçant, unique pour chaque achat, préautorisation ou remboursement indépendant. Pour un remboursement, une complétion ou une correction d’achat, l’ID doit correspondre à celui de la transaction initiale. Prend uniquement des caractères alphanumériques. | |
| polling | V5 | String (chaîne) | Demande à Moneris Cloud d’envoyer le reçu vers une URL temporaire de réception par interrogation cyclique, et retourne cette URL dans la réponse synchrone. Utilisé dans la méthode combinée avec envoi d’URL de rappel. | |
| postBackUrl(request) | V2000 | String (chaîne) | URL HTTPS à laquelle l’application Cloud doit renvoyer la requête. Si absente, Moneris Cloud renvoie l’URL de reçu par interrogation cyclique. | |
| postBackUrl(response) | V2000 | String (chaîne) | Retourne l’URL de rappel définie par le commerçant dans la requête. Uniquement renvoyée si incluse dans la requête. | |
| preTaxAmount | V10 | String (chaîne) | Montant de la transaction avant taxes. La valeur doit être en cents. Exemple : 10,50 $ doit être envoyé comme « 1050 ». | |
| printData | V10000 | String (chaîne) | Données à imprimer par le terminal. Les données peuvent être formatées à l’aide de caractères de contrôle, insérés avant les chaînes de données. Ces caractères restent actifs jusqu’à un autre caractère de contrôle ou un saut de ligne (\n). Valeurs prises en charge : \1 (petite police), \3 (grande police), \B (gras), \I (inversé), \L (aligné à gauche), \C (centré), \R (aligné à droite), \n (nouvelle ligne). | |
| progressStatus | V5 | String (chaîne) | Indicateur précisant si le terminal doit renvoyer des messages d’état à l’ECR durant une transaction. Valeurs : true, false. Disponible uniquement en intégration directe. | |
| realTimeUniqueId | F15 | String (chaîne) | Identifiant unique en temps réel de la transaction Moneris. | |
| receipt | Object (objet) | Reçu de l’étape de validation. Si tous les critères sont remplis, la transaction sera traitée par la passerelle Moneris. À ne pas confondre avec l’objet receipt retourné dans la réponse de transaction. | ||
| referenceNumber | V50 | Number (nombre) | Numéro de référence du paiement. | |
| receiptUrl | V2000 | String (chaîne) | URL endpoint (le point de terminaison) pour interroger le résultat de la transaction. | |
| remainingAmount | V10 | String (chaîne) | Solde restant d’un paiement partiellement autorisé. Différence entre totalAmount et approvedAmount. Si totalAmount et remainingAmount sont présents, le terminal effectuera la transaction sur remainingAmount. Valeur en cents. Exemple : 10,50 $ envoyé comme « 1050 ». | |
| request | Object (objet) | Détails nécessaires pour exécuter la transaction ; objet JSON contenant des paires clé-valeur imbriquées. | ||
| responseCode | V3 | String (chaîne) | < 050 : transaction approuvée. ≥ 050 : transaction refusée. Null : transaction incomplète. Voir le document des codes de réponse sur legacy-developer.moneris.com. | |
| saf | V5 | String (chaîne) | Identifiant pour transaction SAF. | |
| safAllowed | V5 | String (chaîne) | Indique la permission de traiter des transactions SAF. Valeurs :
Valeur Null considérée comme False. | |
| safCounter | V3 | String (chaîne) | Nombre de transactions SAF non traitées. Plage : 1 - 999. Diminue à zéro après chaque traitement en ligne d’une transaction SAF. | |
| sequenceNum | V50 | String (chaîne) | Numéro de référence du paiement. | |
| sessionCounter | V3 | String (chaîne) | Nombre identifiant l’ordre dans lequel le code-barres a été scanné. | |
| settings | Object (objet) | Retourne les paramètres TMS. À déterminer (TBD). | ||
| signatureRequired | Boolean (booléen) | Indicateur de signature requise du titulaire de carte. True : signature requise. False : signature non requise. | ||
| statusCode | V5 | String (chaîne) | Code de réponse. Voir l’annexe C pour la liste complète. | |
| status | V50 | String (chaîne) | Description du code de réponse. Voir l’annexe C pour la liste complète. | |
| storeId | V50 | String (chaîne) | Identifiant unique fourni par Moneris lors de la configuration du compte marchand. | |
| surcharge | V10 | String (chaîne) | Montant des frais pouvant être imputés au titulaire pour une transaction d’achat. Applicables uniquement aux transactions d’achat par débit. Valeur en cents. Exemple : 10,50 $ envoyé comme « 1050 ». | |
| syncModifier | V50 | String (chaîne) | Identifie l’hôte avec lequel synchroniser. Valeurs valides :
| |
| tenderType | V50 | String (chaîne) | Type de paiement : crédit, débit, cadeau, espèces, etc. | |
| terminalId | V8 | String (chaîne) | ID du terminal de destination. | |
| timeout | V2 | String (chaîne) | Définit la durée d’affichage d’un message. Valeur en secondes, max 30. Si non envoyé, le terminal affiche indéfiniment. | |
| tipAmount | V10 | String (chaîne) | Dans la requête : montant de pourboire envoyé par le PDV, remplaçant l’écran de saisie. Dans la réponse : montant saisi par l’utilisateur. Valeur en cents. Exemple : 10,50 $ envoyé comme « 1050 ». | |
| totalAmount | V10 | String (chaîne) | Montant total de la transaction. Valeur en cents. Exemple : 10,50 $ envoyé comme « 1050 ». | |
| track1 | V520 | String (chaîne) | Détails de la piste 1 décrits dans l’ISO 7813. | |
| track2 | V520 | String (chaîne) | Détails de la piste 2 décrits dans l’ISO 7813. | |
| track3 | V520 | String (chaîne) | Données de la piste 3. | |
| trackSelector | V50 | String (chaîne) | Indique quelles données de piste doivent être renvoyées depuis la carte. Valeurs valides :
| |
| transactionId | V50 | String (chaîne) | ID unique généré pour chaque transaction par le PDV. | |
| username | V30 | String (chaîne) | Identifiant unique pour le caissier/utilisateur. | |
| todo | todo | todo | todo |