Codes d'erreur - Neka Paie

Format générique d'erreur

JSON{
  "error": "Description lisible de l'erreur",
  "code": "ERROR_CODE_SYMBOLIC"
}

HTTP 400 — Bad Request

Code	Description
`INVALID_JSON`	Le body n'est pas un JSON valide.
`MALFORMED_REQUEST`	Structure de la requête incorrecte.

HTTP 401 — Unauthorized

Code	Description
`AUTH_FAILED`	Headers d'authentification absents ou clé inconnue.
`SIGNATURE_INVALID`	Signature HMAC ne correspond pas.
`TIMESTAMP_OUT_OF_RANGE`	Timestamp hors fenêtre de ±300 sec.
`API_KEY_REVOKED`	Clé API révoquée ou expirée.

HTTP 403 — Forbidden

Code	Description
`MERCHANT_SUSPENDED`	Compte marchand suspendu.
`MERCHANT_PENDING_KYC`	KYC pas encore validé.
`CASHOUT_APPROVAL_REQUIRED`	Montant > seuil d'approbation, validation back-office requise.
`FEATURE_NOT_AVAILABLE`	Fonctionnalité non activée pour ce marchand.

HTTP 404 — Not Found

Code	Description
`TRANSACTION_NOT_FOUND`	L'ID de transaction n'existe pas ou n'appartient pas au marchand.
`RESOURCE_NOT_FOUND`	Ressource demandée introuvable.

HTTP 409 — Conflict

Conflit d'idempotence : un merchant_order_id identique a déjà été utilisé. Le système renvoie la transaction d'origine sans en créer une nouvelle. Aucune action requise.

HTTP 422 — Unprocessable Entity

Code	Description
`MISSING_REQUIRED_FIELD`	Champ obligatoire absent.
`INVALID_AMOUNT`	Montant ≤ 0 ou type incorrect.
`INVALID_MSISDN`	Format MSISDN invalide.
`UNKNOWN_COUNTRY`	Préfixe MSISDN ne correspond à aucune filiale.
`INSUFFICIENT_BALANCE`	Solde marchand insuffisant pour Cash-Out.
`REFUND_EXCEEDS_AMOUNT`	Montant de remboursement supérieur à l'original.
`TRANSACTION_NOT_REFUNDABLE`	Seules les transactions SUCCESS sont remboursables.

HTTP 429 — Too Many Requests

Code	Description
`RATE_LIMITED`	Limite de débit atteinte. Header `Retry-After` indique le délai à respecter.

HTTP 501 — Not Implemented

Le décaissement (POST /payments/cashout) répond 501 : le contrat d'interface Orange Money AskPayment V2 ne couvre que l'encaissement. Aucun solde n'est débité. L'endpoint se réactive dès qu'Orange fournit le webservice correspondant et qu'il est configuré côté agrégateur.

HTTP 500 / 503 — Erreurs serveur

Code	Description
`OPERATOR_TIMEOUT`	Timeout côté opérateur Orange. La transaction reste PENDING : le push a pu être délivré malgré tout.
`OPERATOR_UNAVAILABLE`	Opérateur Orange non joignable. Réessayer plus tard.
`INTERNAL_ERROR`	Erreur interne. Contacter le support avec le request_id.

Codes Orange Money (`provider_txn_status`)

Sur un échec, failure_reason reprend le code renvoyé par Orange Money et sa signification. Ces codes proviennent du contrat d'interface V2 ; ils sont utiles au support pour expliquer un refus au client final.

Code	Signification
`null`	Avec `provider_state = canceled` : le client n'a pas validé le paiement sur son téléphone.
`200`	Demande reçue et acquittée par Orange Money.
`500`	Système d'information Orange indisponible — statut ambigu, à re-interroger.
`54321`	Échec du paiement — détail disponible via le statut par ID de session.
`60019`	Solde insuffisant sur le compte Orange Money du client.
`00017`	Code secret incorrect.

Seuils du compte client (100004 → 100090)

Ces codes signalent que le client a atteint une limite de son profil Orange Money (par transaction, par jour, par semaine ou par mois). Le client doit contacter Orange : aucune action côté marchand ne peut lever la limite.

Code	Signification
`100004`	Le montant est supérieur au montant par transaction en tant que payeur.
`100006`	Nombre maximum de transactions par jour en tant que payeur atteint.
`100008`	Nombre maximum de transactions par semaine en tant que payeur atteint.
`100010`	Nombre maximum de transactions par mois en tant que payeur atteint.
`100012`	Le nombre maximum de transactions par jour en tant que payeur a été atteint.
`100014`	Le nombre maximum de transactions par semaine en tant que payeur a été atteint.
`100016`	Le nombre maximum de transactions par mois en tant que payeur a été atteint.
`100018`	Le nombre maximum cumulé de transactions par jour en tant que payeur a été atteint.
`100020`	Le nombre maximum cumulé de transactions par semaine en tant que payeur a été atteint.
`100022`	Le nombre maximum cumulé de transactions par mois en tant que payeur a été atteint.
`100024`	Le montant maximum cumulé de transactions par jour en tant que payeur a été atteint.
`100026`	Le montant maximum cumulé de transactions par semaine en tant que payeur a été atteint.
`100028`	Le montant maximum cumulé de transactions par mois en tant que payeur a été atteint.
`100032`	Le montant de la transaction est supérieur au montant maximum par transaction en tant que payeur.
`100052`	Le montant maximum journalier est atteint pour le payeur.
`100054`	Le montant est supérieur au maximum autorisé par jour pour le payeur.
`100058`	Le montant est supérieur au maximum autorisé par transaction pour le payeur.
`100060`	Le nombre maximum cumulé de transactions par jour en tant que payeur est atteint.
`100062`	Le nombre maximum cumulé de transactions par semaine en tant que payeur est atteint.
`100064`	Le nombre maximum cumulé de transactions par mois en tant que payeur est atteint.
`100080`	Le nombre maximum de transactions par jour en tant que payeur a été atteint.
`100082`	Le nombre maximum de transactions par semaine en tant que payeur a été atteint.
`100084`	Le nombre maximum de transactions par mois en tant que payeur a été atteint.
`100086`	Le montant maximum cumulé de transactions par jour en tant que payeur a été atteint.
`100088`	Le montant maximum cumulé de transactions par semaine en tant que payeur a été atteint.
`100090`	Le montant maximum cumulé de transactions par mois en tant que payeur a été atteint.

Codes de retour de la notification Orange

Codes que Neka Paie renvoie à Orange lorsqu'il reçoit une notification de paiement (§2.3 du contrat d'interface). Ils n'apparaissent pas dans l'API marchand.

Code	Signification
`200`	Notification reçue dans le bon format.
`00075`	Numéro client non renseigné.