Cartes enregistrées

Une carte enregistrée appartient à un client (objet customer, identifiant cus_...), lui-même rattaché à votre compte marchand. Le portefeuille est cloisonné : les cartes d'un de vos clients ne sont jamais visibles d'un autre marchand Mobupay.

Deux façons d'obtenir ce client, et elles ne se valent pas :

saveCustomer n'est donc pas une alternative à customerId : c'est la façon d'en obtenir un, à la première commande. Un intégrateur qui s'appuie sur saveCustomer seul, commande après commande, enregistre des cartes que son client ne verra jamais, et son portefeuille se remplit de doublons de la même carte.

Le paramétrage d'un acquéreur carte est complexe, et il n'y a aucune raison qu'il le soit pour vous. Vous déclarez ce que vous voulez faire ; Mobupay traduit, et assume les paramètres les plus favorables. Trois intentions couvrent tous les cas, et elles se déclarent par le champ intention à la création de la session.

POST /api/v1/payments/sessions

{
  "order": { "reference": "CMD-1042", "amount": 4500, "currency": "XPF" },
  "customerId": "cus_2KmBz9aQp4nT8R",
  "intention": "one_click",
  "redirectUrl": "https://boutique.nc/merci",
  "notificationUrl": "https://boutique.nc/webhooks/mobupay"
}

Le champ est facultatif, et son absence ne change rien à vos intégrations existantes : une session qui présentera un portefeuille relève du un clic, les autres du paiement unique.

L'intention se déclare aussi depuis votre espace marchand, à la création d'un lien de paiement et à l'enregistrement d'une carte, avec les mêmes trois choix.

Le webhook payment.authorized que vous recevez déjà porte toujours le customerId :

{
  "type": "payment.authorized",
  "data": {
    "paymentId": "pay_xxxxxxxx",
    "customerId": "cus_2KmBz9aQp4nT8R",
    "customerCreated": true,
    "paymentMethodId": "pm_xxxxxxxx",
    "cardBrand": "VISA",
    "cardLast4": "4242"
  }
}

Écrivez data.customerId sur l'utilisateur concerné dans votre base, à la réception. Vous n'avez rien d'autre à appeler : la correspondance se construit toute seule au fil des commandes.

paymentMethodId vous dit en prime qu'une carte vient d'être enregistrée, et customerCreated distingue une fiche créée d'une fiche retrouvée.

Plus robuste que d'attendre le premier paiement : créez la fiche au moment où l'utilisateur ouvre un compte chez vous.

curl -X POST https://api.mobupay.nc/api/v1/customers \
  -H "Authorization: Bearer sk_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "client@example.com",
    "externalId": "votre-identifiant-utilisateur",
    "firstName": "Prénom",
    "lastName": "Nom"
  }'

externalId est le champ important : c'est votre identifiant, celui que vous maîtrisez. Il vous permet de retrouver la fiche sans dépendre de l'adresse de courriel, qu'un client peut changer.

Si l'adresse ou l'externalId existe déjà, l'API répond 409 et ne renvoie pas la fiche. Retrouvez-la alors par une recherche :

GET /api/v1/customers?externalId=votre-identifiant-utilisateur
GET /api/v1/customers?email=client@example.com

Première commande, client encore inconnu :

{
  "order": { "amount": 3500, "currency": "XPF", "reference": "CMD-1042" },
  "email": "client@example.com",
  "saveCustomer": true,
  "allowCustomerToSavePaymentMethod": true,
  "redirectUrl": "https://example.com/retour",
  "notificationUrl": "https://example.com/webhook"
}

Commandes suivantes, une fois que vous avez son cus_... :

{
  "order": { "amount": 2800, "currency": "XPF", "reference": "CMD-1108" },
  "customerId": "cus_2KmBz9aQp4nT8R",
  "allowCustomerToSavePaymentMethod": true,
  "redirectUrl": "https://example.com/retour",
  "notificationUrl": "https://example.com/webhook"
}

• customerId et saveCustomer ne s'emploient pas ensemble : quand vous connaissez le client, la fiche existe déjà.
• Gardez allowCustomerToSavePaymentMethod à true : c'est ce qui autorise le client à enregistrer une nouvelle carte, y compris quand il en a déjà.
• La case est présentée déjà cochée. Si votre parcours exige un consentement explicite, passez savePaymentMethodCheckedByDefault à false : la case s'affiche alors vide, et seul un geste de votre client l'active.
• Pour un utilisateur non connecté, gardez le premier format. Le mélange des deux régimes est prévu et sans danger.
• Un cus_ de l'environnement de test ne fonctionne pas en production, et réciproquement : chaque environnement a ses propres fiches. Un identifiant qui n'appartient pas à votre compte donne une erreur 400 CUSTOMER_NOT_FOUND.

Sur une clé de test, dans cet ordre :

1. Une première commande avec email + saveCustomer, en cochant l'enregistrement de la carte. Relevez le customerId du webhook.
2. Une seconde commande pour le même utilisateur, avec customerId. La page doit afficher la carte enregistrée et un bouton de paiement en un clic, et non un formulaire vierge.
3. Une troisième en enregistrant une deuxième carte : les deux doivent apparaître, et la carte par défaut être présélectionnée.

Si l'étape 2 affiche encore un formulaire vierge, le customerId n'est pas parti dans le corps de la requête : vérifiez vos journaux d'appel avant toute autre piste.

Sur un paiement en un clic, Mobupay peut demander à la banque du porteur de ne pas l'authentifier. C'est Mobupay qui décide, paiement par paiement, dans les limites que vous avez réglées : votre intégration n'a rien à envoyer, et aucun champ de l'API ne déclenche l'exemption.

Une exemption n'est demandée que si toutes ces conditions sont réunies :

• le porteur paie lui-même avec une carte enregistrée (intention one_click) ;
• la carte a déjà été authentifiée chez vous ;
• le montant ne dépasse pas votre seuil : 100 € par défaut, 250 € au plus ;
• la carte n'a pas atteint votre nombre de paiements exemptés sur 24 heures : 3 par défaut, 5 au plus ;
• la carte est une carte CB, si vous gardez ce critère ;
• aucun remboursement ni aucune contestation sur cette carte chez vous depuis 180 jours ;
• au plus 5 % de vos paiements remboursés sur les 90 derniers jours.

Ne sont jamais exemptés : l'enregistrement d'une carte et le premier paiement qui l'enregistre, les prélèvements faits sans le porteur (intention unscheduled), et les paiements encaissés sur le contrat d'encaissement Mobupay.

La banque garde le dernier mot : elle peut accorder l'exemption, authentifier le porteur sans défi, ou lui en présenter un. Si elle refuse l'exemption, Mobupay relance une fois l'authentification, sans exemption, sur la même carte.

Le bloc authentication de la lecture d'un paiement dit ce que la banque a répondu : exempted vaut true quand elle a accordé l'exemption, et liabilityShift dit si la responsabilité a été transférée. Ces champs valent null tant que la réponse n'est pas connue.