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 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à.
• 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.