Erreurs

Format

Les erreurs HTTP 4xx/5xx suivent l'enveloppe ApiResponse de la plateforme.

{
  "success": false,
  "error": {
    "code": "MERCHANT_KYB_NOT_APPROVED",
    "message": "Merchant cannot transact until KYB is APPROVED...",
    "details": {}
  }
}

Codes fréquents

• Invalid API key (401) — clé révoquée ou incorrecte
• MERCHANT_KYB_NOT_APPROVED (400) — onboarding incomplet ou modification légale en revue
• KYB_USE_PROFILE_ENDPOINT (400) — utiliser les endpoints profile pour un dossier approuvé
• KYB_SUPPLEMENTAL_DOCS_REQUIRED (400) — documents complémentaires manquants
• INVALID_MERCHANT_SCOPE (403) — merchantId hors scope clé
• INSUFFICIENT_PERMISSIONS (403) — permission manquante
• IDEMPOTENCY_KEY_REQUIRED (400) — header Idempotency-Key manquant
• CHECKOUT_SESSION_EXPIRED (409) — checkout expiré
• CHECKOUT_SESSION_NOT_OPEN (409) — session non payable
• PAYMENT_FAILED (409) — échec paiement
• PAYMENT_LINK_EXPIRED (409) — lien de paiement expiré
• PAYMENT_LINK_MAX_USES_REACHED (409) — quota d'utilisations atteint
• PAYMENT_LINK_NOT_ACTIVE (409) — lien annulé ou inactif
• PAYMENT_LINK_SLUG_TAKEN (409) — slug déjà utilisé

Codes d'échec checkout (failureCode)

Sur GET /checkout/pay/:sessionId, GET /checkout/pay/:sessionId/status et le webhook payment.failed, failureCode expose un vocabulaire IZZIPAY stable — ce n'est plus un code provider brut.

Breaking change : les intégrations qui parsaient INSUFFICIENT_BALANCE (PawaPay) doivent migrer vers INSUFFICIENT_FUNDS.

failureMessage est le message payeur (FR pour l'instant). Le champ webhook reason reste un alias deprecated du code provider interne.

• PAYMENT_NOT_CONFIRMED — Le payeur n'a pas validé le paiement (PIN, OTP ou autorisation mobile). (message payeur : Vous n'avez pas confirmé le paiement sur votre téléphone (PIN ou autorisation). Réessayez.)
• INSUFFICIENT_FUNDS — Fonds insuffisants sur le compte du payeur. (message payeur : Votre compte mobile money n'a pas assez de fonds pour ce paiement.)
• PAYMENT_IN_PROGRESS — Un autre paiement est déjà en cours pour ce numéro ou ce compte. (message payeur : Un paiement est déjà en cours sur ce numéro. Terminez-le ou attendez quelques minutes avant de réessayer.)
• PAYER_NOT_FOUND — Le numéro ou le compte payeur est inconnu chez l'opérateur. (message payeur : Ce numéro n'est pas enregistré avec l'opérateur mobile sélectionné.)
• LIMIT_EXCEEDED — Plafond portefeuille ou limite transactionnelle atteinte. (message payeur : Vous avez atteint la limite de votre portefeuille mobile money.)
• INVALID_RECIPIENT — Numéro, IBAN ou destinataire invalide pour le rail choisi. (message payeur : Le numéro de téléphone ne correspond pas au pays ou à l'opérateur. Vérifiez le numéro saisi.)
• AMOUNT_OUT_OF_BOUNDS — Montant hors limites autorisées par le provider ou la région. (message payeur : Le montant dépasse la limite du paiement mobile. Réduisez le montant ou choisissez une autre méthode.)
• INVALID_AMOUNT — Format ou granularité du montant refusée. (message payeur : Le format du montant n'est pas accepté par l'opérateur mobile.)
• INVALID_CURRENCY — Devise non supportée pour la méthode sélectionnée. (message payeur : Cette devise n'est pas acceptée pour ce mode de paiement.)
• PROVIDER_UNAVAILABLE — Provider ou opérateur temporairement indisponible côté acquéreur. (message payeur : Le service de paiement mobile est temporairement indisponible. Réessayez plus tard.)
• CARD_DECLINED — Carte refusée par l'émetteur ou le réseau. (message payeur : Votre carte a été refusée. Vérifiez vos informations ou contactez votre banque.)
• PAYMENT_CANCELLED — Paiement annulé par le payeur ou expiré côté provider. (message payeur : Le paiement a été annulé.)
• RISK_BLOCKED — Blocage conformité / risque avant ou pendant le paiement. (message payeur : Le paiement a été bloqué pour des raisons de sécurité. Contactez le support.)
• UNKNOWN — Échec non classifié — consulter les logs ou le support. (message payeur : Le paiement n'a pas pu être finalisé. Vérifiez vos informations ou réessayez.)

Pagination

Les listes (charges, sessions, liens, payouts) retournent data comme tableau et meta { page, pageSize, total, totalPages }.

La taille de page par défaut est 25 (DEFAULT_PAGE_SIZE).

GET /payments/charges accepte aussi starting_after (curseur sur l'ID charge) pour parcourir de grands volumes.