Services de mode de paiement

La fonctionnalité Mode de paiement repose sur cinq API :

1. Créer un mode de paiement
2. Récupérer le mode de paiement
3. Répertorier les modes de paiement
4. Mettre à jour le mode de paiement (PUT et PATCH)
5. Supprimer le mode de paiement

1. Créer un mode de paiement

L’exemple ci-dessous présente une requête de création de mode de paiement pour une carte de crédit, avec paymentMethodSource = CARD et le format de jeton permanentTokenFormat = 2U. La réponse contient l’ID du mode de paiement (paymentMethodId), confirme le format du jeton (permanentTokenFormat) et fournit la valeur du jeton (permanentToken).

{
    "idempotencyKey": "78159eb6-52e6-4d36-b9cb-0ba35321c192",
    "cardholderInformation": {
        "cardholderName": "Name",
        "companyName": "Company Name Ltd"
    },
    "contactDetails": {
        "phoneNumber": "+18663197450",
        "email": "[email protected]"
    },
    "billingAddress": {
        "unitNumber": "1234A",
        "streetNumber": "1234",
        "streetName": "Street Name",
        "city": "City Name",
        "province": "AA",
        "postalCode": "M8X 2X2",
        "country": "CA"
    },
    "paymentMethodSource": "CARD",
    "card": {
        "cardNumber": "NNNNNNNNNNNNNNNNNNN",
        "expiryMonth": MM,
        "expiryYear": YYYY,
        "cardSecurityCode": NNN
    },
    permanentTokenFormat: "2U", - default value = 0
    "customData": {
        "property1": "string",
        "property2": "string"
    }
}

{
    "paymentMethodId": "pmid",
    "merchantId": "0030100684886",
    "cardholderInformation": {
        "cardholderName": "Name",
        "cardholderNameDetails": null,
        "companyName": "Company Name Ltd"
    },
    "contactDetails": {
        "phoneNumber": "+18663197450",
        "email": "[email protected]"
    },
    "billingAddress": {
        "unitNumber": "1234A",
        "streetNumber": "1234",
        "streetName": "Street Name",
        "city": "City Name",
        "province": "AA",
        "postalCode": "M8X 2X2",
        "country": "CA"
    },
    "paymentMethodInformation": {
        "paymentMethodType": "CARD",
        "cardInformation": {
            "bankIdentificationNumber": "NNNNNN",
            "lastFour": "NNNN",
            "expiryMonth": MM,
            "expiryYear": YYYY,
            "cardBrand": "CARD BRAND",
            "cardType": "Card Type",
            "cardFingerprint": null,
            "issuer": null
        },
        "paymentAccountReference": null,
        "storePaymentMethod": "store or not store pmID", - Defaults = DO_NOT_STORE
        "paymentMethodSource": "paymet method source"
    },
    permanentTokenFormat: "2U" 
    permanentToken: "Data key" 
    "createdAt": "YYYY-MM-DDTHH:MM:SS.MLSZ",
    "modifiedAt": "YYYY-MM-DDTHH:MM:SS.MLSZ",
    "customData": {
        "property1": "string",
        "property2": "string"
    }
}

2. Récupérer le mode de paiement

L’API Récupérer le mode de paiement effectue une opération de lecture simple, mais essentielle : elle donne accès à l’état actuel et aux détails d’un mode de paiement existant à partir de son ID. Elle accepte également une clé de données (Data key) existante et en retourne les détails. Ajouter l’ID du mode de paiement ou la clé de données à l’en-tête de la requête.

Contenu de la réponse

L’API retourne un objet Mode de paiement ou une clé de données. La réponse comprend généralement les données d’identification, les renseignements sur le titulaire de carte, l’adresse de facturation et les détails du mode de paiement.

Raisons d’utiliser cette API

• Afficher les renseignements de paiement ou la clé de données enregistrés, limités aux données non sensibles : présenter les cartes enregistrées dans les paramètres du compte
• Valider un mode de paiement avant son utilisation : avant de porter un montant à la carte, confirmer que le mode de paiement appartient bien au commerçant et au client visés
• Diagnostiquer et rapprocher les données : vérifier ce qui a réellement été enregistré ou analyser des problèmes liés aux transactions

3. Répertorier les modes de paiement

L’API Répertorier les modes de paiement retourne un ensemble de modes de paiement, habituellement ceux d’un commerçant ou d’un client donné, plutôt qu’un seul. Elle produit une liste paginée des modes de paiement enregistrés qui correspondent aux filtres appliqués, par exemple le client, le commerçant ou d’autres critères. Seuls les modes de paiement permanents figurent dans la liste : les modes temporaires en sont exclus, même s’ils ne sont pas expirés. La clé de données associée à un mode de paiement permanent n’est pas retournée.

Raisons d’utiliser cette API

• Afficher tous les modes de paiement enregistrés : présenter au client l’ensemble de ses modes de paiement, puis lui permettre d’en choisir un, d’en supprimer un ou d’en désigner un par défaut
• Gérer les profils des clients : si vos systèmes associent les clients à leurs modes de paiement, afficher ceux-ci au moment du passage à la caisse
• Outils administratifs et de soutien : permettre à vos systèmes internes de vérifier les modes de paiement enregistrés, d’analyser des problèmes ou de soutenir le service à la clientèle
• Traitements par lots et gestion du cycle de vie : repérer les cartes expirées, examiner les modes de paiement inactifs et supprimer ceux qui ne servent plus

Caractéristiques de la réponse

• La réponse est une liste paginée
• Contrairement à l’API Récupérer le mode de paiement, qui retourne les détails d’un seul mode de paiement à partir de son ID, cette API retourne l’ensemble des modes de paiement enregistrés
• Filtres pris en charge : customerId, paymentMethodType, plages de dates et paramètres de pagination (limit et offset)
• La pagination est obligatoire : toujours paginer les résultats pour éviter les réponses volumineuses
• Seules des données non sensibles sont retournées : marque de la carte et quatre derniers chiffres, sans le numéro de carte complet ni le numéro de vérification de carte (NVC)

4. Mettre à jour le mode de paiement

L’API Mettre à jour le mode de paiement permet de mettre à jour les attributs modifiables d’un mode de paiement déjà créé et enregistré, sans en créer un nouveau.

Elle prend également en charge les mises à jour lorsque le commerçant fournit une clé de données existante. Concrètement, l’API de Moneris vérifie si cette clé de données est déjà liée à un mode de paiement enregistré, puis met à jour le système de référence approprié.

Guide de décision

• ID du mode de paiement avec jeton permanent : l’API de Moneris met à jour le mode de paiement enregistré et répercute la modification sur la clé de données associée, de sorte que les deux enregistrements demeurent concordants.
• ID du mode de paiement sans jeton permanent : l’API de Moneris met à jour uniquement le mode de paiement enregistré, puisqu’aucune clé de données n’est à synchroniser.
• Clé de données déjà associée à un mode de paiement : l’API de Moneris met à jour le mode de paiement enregistré qui y est lié ainsi que la clé de données correspondante, ce qui assure la cohérence du profil de paiement du client d’un système à l’autre.
• Clé de données sans association : l’API de Moneris met à jour uniquement la clé de données, puisqu’aucun mode de paiement enregistré n’y est rattaché.

La réponse conserve la même structure dans tous les cas. Lorsque la situation s’y prête, elle indique clairement le format de la clé de données ainsi que la clé elle-même, afin que les systèmes en aval puissent traiter uniformément le mode de paiement mis à jour.

Éléments pouvant être mis à jour

• Renseignements sur la carte : numéro de carte et numéro de vérification de carte (NVC)
• Renseignements sur le titulaire de carte : nom
• Coordonnées : adresse de courriel et numéro de téléphone
• Adresse de facturation

L’API Mettre à jour le mode de paiement prend en charge deux méthodes : PUT et PATCH. Utiliser PUT pour remplacer l’objet associé à l’ID du mode de paiement et PATCH pour le modifier partiellement.

Raisons d’utiliser cette API

• Mettre à jour les renseignements sur le titulaire de carte ou l’adresse de facturation : le client modifie son profil
• Corriger des données inexactes ou incomplètes : les données initiales étaient partielles ou erronées, et le client les complète ou les corrige par la suite
• Gérer les métadonnées et les champs personnalisés : si vos systèmes conservent ces renseignements, il est possible de les modifier sans toucher aux données de paiement

5. Supprimer le mode de paiement

L’API Supprimer le mode de paiement retire définitivement un mode de paiement enregistré de l’API de Moneris : il ne peut plus servir à des transactions ultérieures. Cette API s’applique uniquement aux modes de paiement permanents ainsi qu’aux clés de données.

L’API Supprimer le mode de paiement peut également supprimer la clé de données associée. Ce comportement dépend du type d’identifiant fourni et de l’existence d’une association avec un mode de paiement, comme le résume la section suivante.

Portée de la suppression selon le cas

• Avec l’ID d’un mode de paiement permanent, Moneris supprime à la fois l’enregistrement du mode de paiement et la clé de données correspondante de la passerelle.
• Avec l’ID d’un mode de paiement temporaire, Moneris supprime uniquement l’enregistrement du mode de paiement.
• Avec une clé de données liée à un mode de paiement enregistré, Moneris supprime à la fois l’enregistrement du mode de paiement et la clé de données de la passerelle.
• Avec une clé de données qui n’est liée à aucun mode de paiement enregistré, Moneris supprime uniquement la clé de données de la passerelle.

Raisons d’utiliser cette API

• Suppression par le client : le client accède à la section Cartes enregistrées et sélectionne Supprimer la carte
• Conformité et minimisation des données : de nombreuses réglementations et pratiques exemplaires exigent de ne pas conserver les données de paiement plus longtemps que nécessaire, ou de permettre aux clients de supprimer leurs données
• Prévention des facturations non souhaitées : aucun montant ne peut plus être porté à ce mode de paiement
• Remplacement des modes de paiement désuets

Conséquences de la suppression

• Le mode de paiement devient inutilisable : toute tentative de paiement ou de récupération au moyen du mode de paiement ou de la clé de données supprimés échoue
• Un nouveau mode de paiement doit être créé : le client doit saisir de nouveau ses renseignements s’il souhaite s’en servir plus tard