Fonctionnalités des modes de paiement

Cette page présente les fonctionnalités offertes pour la création et la gestion des modes de paiement avec l’API de Moneris : le rôle de l’unicité dans la prévention des doublons, la transformation en jetons des données de carte ou la réutilisation d’une clé de données existante, le fonctionnement des formats de jeton permanent et l’incidence de la transformation en jetons sur les programmes de fidélisation des marques de carte.

Unicité

Lorsqu’un commerçant crée un mode de paiement, le système doit déterminer si cet instrument de paiement précis — une carte de crédit donnée, par exemple — est déjà enregistré. La fonctionnalité d’unicité effectue cette vérification à partir de facteurs définis par l’entreprise, tels que l’ID du commerçant et l’empreinte de la carte. Lorsqu’il trouve une correspondance, le système retourne l’enregistrement existant au lieu de créer un doublon.

Pourquoi cette fonctionnalité est-elle importante? Sans unicité, le commerçant risque d’accumuler plusieurs modes de paiement pour une même carte. Cette accumulation nuit au rapprochement des comptes et à la gestion du cycle de vie, en plus d’accroître les risques d’erreur. L’unicité garantit un seul mode de paiement par carte et par commerçant, ce qui simplifie la gestion des données.

Il importe de distinguer l’unicité de l’idempotence. L’idempotence empêche la soumission répétée d’une requête identique, par exemple lors d’une nouvelle tentative. L’unicité agit plutôt sur le plan des affaires : même si les métadonnées des requêtes diffèrent, elle reconnaît la même carte et évite les doublons. L’idempotence gère les nouvelles tentatives techniques, tandis que l’unicité protège l’intégrité des données. Ensemble, ces deux mécanismes assurent la fiabilité du répertoire des modes de paiement et en limitent l’encombrement.

Transformation en jetons des cartes au moyen de l’API de Moneris

Pour créer un mode de paiement au moyen de l’API de Moneris, le commerçant dispose de deux méthodes, selon qu’il part de données de carte brutes ou qu’il possède déjà une clé de données.

Option 1 — Transmettre les données de la carte (nouvelle transformation en jetons)

Le commerçant qui ne possède pas encore de clé de données transmet directement dans sa requête les renseignements complets de la carte : le numéro, la date d’expiration et le code de vérification (CVV). L’API de Moneris transforme alors la carte en jeton selon le format indiqué dans le champ facultatif permanentTokenFormat, crée un mode de paiement, puis retourne trois renseignements essentiels : le paymentMethodId (par exemple, pm0001KT7BWW…), le permanentToken (la clé de données) et le format utilisé. Un seul appel à l’API fournit donc à la fois un ID du mode de paiement et une clé de données, sans étape distincte de transformation en jetons.

Option 2 — Transmettre une clé de données existante (réutilisation)

Le commerçant qui possède déjà une clé de données la transmet directement dans sa requête de création. L’API de Moneris associe cette clé de données à un nouvel ID du mode de paiement, sans nouvelle transformation en jetons ni appel supplémentaire. La réponse retourne la clé de données transmise, désormais associée à un ID du mode de paiement. Cette méthode n’exige aucune conversion de données, n’ajoute aucune latence et assure une compatibilité complète entre les systèmes : le commerçant continue d’utiliser la même clé de données dans l’API de Moneris et dans les autres applications de Moneris.

Quelle option choisir?

Pour un nouveau commerçant ou pour l’enregistrement de nouvelles cartes, retenir l’option 1, qui permet de tout créer en une seule étape. Pour un commerçant qui utilise déjà des clés de données, retenir l’option 2 : ces jetons s’intègrent à l’API de Moneris sans migration, et le commerçant continue d’utiliser ce qu’il possède déjà.

Format du jeton permanent de la clé de données

Lors de la création d’un ID du mode de paiement à partir de données de carte (option 1), le champ permanentTokenFormat de la requête détermine la forme du jeton permanent, soit la clé de données. Ce champ agit comme un sélecteur de préférence : il indique au système le format de jeton à retourner, selon les besoins de votre intégration.

Fonctionnement

Lorsque la transformation en jetons d’une carte réussit, le système génère une clé de données qui représente cette carte pour une utilisation ultérieure. Le format du jeton dépend de la valeur transmise :

Valeur	Résultat obtenu
0 ou vide	Un jeton alphanumérique standard de 25 caractères (par exemple, `aBcDeFgHiJkLmNoPqRsTuVwXy`) — aucun chiffre de la carte n’est visible.
1	Un jeton qui conserve les six premiers et les quatre derniers chiffres du numéro de carte et qui respecte la longueur du numéro d’origine. Utile si vos systèmes en aval attendent une valeur qui « ressemble » à un numéro de carte.
2	Comme la valeur précédente (six premiers et quatre derniers chiffres visibles), mais sans conserver la longueur du numéro de carte d’origine : le jeton peut être plus court ou plus long que le PAN.
0U	Comme `0` (25 caractères alphanumériques), mais unique : le système garantit que la transformation en jetons de la même carte retourne toujours le même jeton.
1U	Comme `1` (six premiers et quatre derniers chiffres, longueur conservée), mais unique.
2U	Comme `2` (six premiers et quatre derniers chiffres, longueur non conservée), mais unique.
4U	Six premiers et quatre derniers chiffres visibles, longueur non conservée, avec caractères alphabétiques garantis dans la portion générée, et unique.

Signification de la mention « unique »

Avec un format qui se termine par la lettre U, le système retourne toujours le même jeton lorsque la même carte est transformée en jetons plus d’une fois pour un même ID du commerçant, au lieu d’en générer un nouveau chaque fois. Cette garantie facilite l’élimination des doublons : la valeur du jeton suffit à déterminer si une carte est déjà enregistrée, sans recherche supplémentaire.

Si le champ est omis, ou si la valeur 0 est transmise, le jeton retourné compte 25 caractères et n’offre aucune garantie d’unicité. La transformation en jetons d’une même carte à deux reprises, pour un même ID du commerçant, peut alors produire deux jetons différents.

Recommandation

Si votre système doit détecter les cartes en double ou éviter d’enregistrer plusieurs fois la même carte, choisir un des formats uniques (U). Si une visibilité partielle du numéro de carte est également nécessaire pour l’affichage ou l’acheminement, combiner l’unicité au format 1U, 2U ou 4U, selon que la longueur doit être conservée ou que des caractères alphabétiques doivent être garantis.

Programmes de fidélisation des marques de carte

La génération d’une clé de données pour une carte par l’API de Moneris n’a aucune incidence sur les programmes de fidélisation de la marque de carte associés à cette carte, comme les récompenses Visa ou Mastercard.

La clé de données remplace le numéro de carte uniquement pour le stockage chez le commerçant. Au moment du traitement d’une transaction, le réseau de la marque de carte reçoit toujours tous les renseignements dont il a besoin, y compris la référence du compte de paiement (PAR, pour Payment Account Reference), afin d’attribuer l’achat au profil de fidélisation du titulaire de carte. Les points, les récompenses et les avantages liés au niveau d’adhésion continuent de s’accumuler normalement. Le commerçant peut donc adopter les clés de données en toute confiance : les avantages de fidélisation de ses clients demeurent entièrement intacts.