Chargement de vos clés API…
Erreurs
Format des erreurs et codes principaux retournés par l'API.
Format JSON
Toutes les erreurs retournent un corps JSON normalisé :
{
"error": "ValidationError",
"message": "La requête est invalide.",
"statusCode": 400,
"fields": [
{ "field": "order.amount", "message": "Required", "code": "invalid_type" }
],
"requestId": "c65236d2-0f90-424a-88a9-515dc5d320fb"
}Conservez requestId dans vos logs : c'est ce qu'on vous demandera en cas de support. Le détail par champ (fields[].message) est le message du validateur, le plus souvent en anglais : fondez votre logique sur field et code, jamais sur le libellé.
Codes HTTP
| Code | Label | Signification |
|---|---|---|
| 200 | OK | Requête réussie. |
| 201 | Created | Ressource créée avec succès. |
| 204 | No Content | Suppression réussie, pas de corps. |
| 400 | Bad Request | Paramètres invalides ou manquants. |
| 401 | Unauthorized | Clé API manquante ou invalide. |
| 403 | Forbidden | Permission insuffisante ou IP non autorisée. |
| 404 | Not Found | Ressource introuvable. |
| 409 | Conflict | Conflit (idempotence, doublon, état incompatible). |
| 422 | Unprocessable Entity | Validation métier échouée. |
| 429 | Too Many Requests | Rate limit dépassé. Réessayez après le délai indiqué dans `Retry-After`. |
| 500 | Internal Server Error | Erreur côté Mobupay. Si persistant, contactez le support. |
| 502 | Bad Gateway | Erreur du processeur en aval (banque, réseau carte, etc.). |
Codes d'erreur métier
Le champ error du JSON contient un code machine que vous pouvez switcher dans votre code. Codes les plus fréquents :
| Code | Signification |
|---|---|
| VALIDATION_ERROR | Champ requis manquant ou mal formaté. Voir `fields` dans la réponse. |
| AUTHENTICATION_ERROR | Clé API invalide ou révoquée. |
| PERMISSION_ERROR | La clé n'a pas la permission requise pour cette opération. |
| NOT_FOUND | L'identifiant demandé n'existe pas dans votre compte. |
| IDEMPOTENCY_KEY_REUSED | La clé d'idempotence a déjà servi à une demande différente (autre paiement, autre opération ou autre contenu). Une nouvelle opération demande une nouvelle clé. |
| IDEMPOTENCY_KEY_INVALID | L'en-tête `Idempotency-Key` dépasse 255 caractères. Utilisez une clé plus courte, un UUID v4 par exemple. |
| IDEMPOTENCY_REQUEST_IN_PROGRESS | La première demande envoyée sous cette clé d'idempotence est encore en cours. Renvoyez-la à l'identique, avec la même clé, quelques secondes plus tard. |
| IDEMPOTENCY_OUTCOME_UNKNOWN | La première demande envoyée sous cette clé d'idempotence a échoué après l'envoi de l'opération à l'acquéreur ou à la banque : son issue est inconnue, et la clé ne la rejouera pas. Consultez l'objet concerné (paiement, remboursement, virement) avant de réessayer, puis renvoyez la demande avec une nouvelle clé seulement si l'opération n'a pas eu lieu. Nos équipes sont prévenues. |
| CAPTURE_AMOUNT_EXCEEDS_REMAINING | Le montant à capturer dépasse le montant autorisé. `details.remainingAmount` donne ce qui peut être capturé ; sans montant, la capture porte sur tout l'autorisé. |
| CAPTURE_ALREADY_DONE | Le paiement a déjà été capturé. Un paiement ne se capture qu'une fois : une capture partielle est finale et rend le reste de l'autorisation au client. |
| INVALID_PAYMENT_STATUS | Opération impossible dans l'état actuel du paiement (ex : capturer un paiement déjà capturé). |
| REFUND_AMOUNT_EXCEEDS_PAYMENT | Le montant à rembourser dépasse le montant initial. |
| FREE_PAYMENT_UNSUPPORTED | `order.amount` doit être strictement positif : un paiement gratuit ne peut pas être créé. Un net carte nul n'est autorisé qu'en mode plateforme entièrement couvert par une remise (`order.discount = order.amount`). |
| PLATFORM_CONFIG_REQUIRED_NET0 | Capture d'un paiement à net 0 (entièrement financé par la plateforme) sans `order.platformConfig` : le split est requis à la capture pour ventiler aux sous-marchands. |
| PARTIAL_REFUND_UNSUPPORTED_NET0 | Remboursement partiel d'un paiement à net 0 : seul le remboursement total est possible (le net carte est nul). Omettez `amountCents`. |
| CAPTURE_AMOUNT_MISMATCH | Le montant capturé doit être égal à `order.amount − order.discount` (+ pourboires en top-up) : la carte n'est débitée que du net, la plateforme abonde le complément. |
| ENTRY_AMOUNT_MISMATCH | Le montant d'une entrée `platformConfig` ne correspond pas à la somme de ses articles TTC remisés (`Σ(unitPrice×qty − discount) − discount`). |
| PLATFORM_SELF_NO_COMMISSION | Une entrée `platformConfig` marquée `isPlatform` ne peut porter aucune commission (`platformCommission` / `itemPlatformCommission` / `orderPlatformCommission`) : on ne se prélève pas de commission sur soi-même. |
| PLATFORM_SELF_REQUIRES_SUBMERCHANT | Une entrée `isPlatform` requiert au moins une autre entrée sous-marchand. Pour une commande de la plateforme pour elle-même seule, utilisez le mode e-commerce (sans `platformConfig`). |
| CAPTURE_AMOUNT_BELOW_AUTHORIZED | À la capture, `order.amount` (brut) doit égaler le montant autorisé (ou le dépasser en top-up plateforme, cf. CAPTURE_AMOUNT_EXCEEDS_AUTHORIZED_UNFUNDED). Une réduction du montant débité n'est permise que via un `order.discount` explicite ; une sous-capture « sèche » est refusée (elle masquerait une intégration incomplète). |
| CAPTURE_AMOUNT_EXCEEDS_AUTHORIZED_UNFUNDED | À la capture, `order.amount` dépasse le montant autorisé sans qu'une remise financée par la plateforme couvre l'excédent. Top-up plateforme : `(order.amount − order.discount) + Σ pourboires` doit rester ≤ montant autorisé — la carte n'est jamais débitée au-delà de son empreinte. |
| UNKNOWN_STORE | Le `storeId` transmis ne correspond à aucune boutique de votre compte, ni par identifiant (`sto_*`), ni par code. La boutique n'est jamais ignorée en silence : l'appel échoue. Vérifiez aussi que le champ est bien de premier niveau, et non placé dans `order`, où toute clé inconnue est écartée sans erreur. |
| STORE_INACTIVE | La boutique existe mais elle est désactivée. Réactivez-la depuis votre espace marchand, Paramètres puis Mes offres : ouvrez le carré de la boutique. |
| STORE_KIND_MISMATCH | La boutique visée est déclarée point de vente physique : elle n'encaisse pas à distance. Employez une boutique en ligne pour un paiement distant. |
| STORE_CONTRACT_INACTIVE | Le contrat d'encaissement rattaché à cette boutique n'est plus actif. Aucun repli silencieux sur le contrat par défaut n'est fait : il changerait le libellé porté au relevé du client et la ventilation des fonds sans le dire. |
| STORE_CONTRACT_CONFLICT | L'appel (`merchantConfigId`) et la boutique (`storeId`) désignent deux contrats d'encaissement différents. Ne transmettez que l'un des deux : la voie normale est la boutique. |
| STORE_KEY_MISMATCH | Votre clé API est rattachée à une boutique, et l'appel en nomme une autre. Une clé installée sur un site fait autorité : le corps peut la répéter, jamais la contredire. |
| RATE_LIMITED | Trop de requêtes. Voir header `Retry-After`. |
| REFUND_PROCESSOR_FAILED | Erreur côté processeur carte. Réessayez plus tard ou contactez le support. |
Bonnes pratiques
- Switcher sur
statusCode+error(jamais sur le texte demessagequi peut évoluer). - Ne rejouez que sur 429 (avec un délai croissant) et 502/503/504 (incident passager).
- Exception, la capture : un
502 MONEXT_CAPTURE_FAILEDne se rejoue que sidetails.retryablevauttrue. Mobupay a alors vérifié auprès de l'acquéreur que rien n'a été capturé. Sinon, lisez le paiement avant de capturer à nouveau. - Logger
requestIdsystématiquement. - Pour les 4xx : corrigez la demande avant de la rejouer, sinon vous bouclez à perte.