Aller au contenu

Diagnostiquer un problème

Demandez à la CLI ce qui est arrivé à un paiement, un transfert, un remboursement ou un événement, qui doit agir et quoi faire ensuite.

wajub debug prend un identifiant et explique l'objet qui se trouve derrière : ce qui s'est passé et quand, pourquoi il a échoué ou reste bloqué, qui doit agir, et l'étape suivante avec la page de documentation qui la décrit. wajub explain est la même commande.

Si votre CLI ne connaît pas la commande

La réponse "debug" is not a wajub command signifie que votre CLI lui est antérieure, et npm install -g @wajub/cli la met à jour.

Une commande payée dont votre serveur n'a rien su
$ wajub debug trx_test_CSUGajfv9xh0XQ5wu2lx

Payment trx_test_CSUGajfv9xh0XQ5wu2lx  succeeded  (sandbox)
Nothing reliable tells your server this payment succeeded

Timeline (UTC)
  2026-11-20 09:14:02  payment created  5000 XAF · reference order-4172
  2026-11-20 09:14:31  event payment.succeeded  evt_test_Nq8rT3vK6mX2pW9cB5jL7hYs · delivered
  2026-11-20 09:14:31  last update  succeeded · cm.mtn

Diagnosis
  ✗  Nothing reliable tells your server this payment succeeded  [your integration]
     Only the callback redirect tells you, and it never comes when the payer closes the tab before being sent back.
     → Subscribe an endpoint to `payment.succeeded` and fulfil from it, after retrieving the payment server-side.
     https://docs.wajub.com/developer-tools/webhooks/quickstart
  ✗  No endpoint receives `payment.succeeded`  [your integration]
     1 enabled endpoint(s), none subscribed to `payment.succeeded`.
     → Add `payment.succeeded` to your endpoint's events with `wajub webhooks update <id> --data-raw '{"events":[…]}'` (the list replaces the old one), then `wajub events resend <evt_id>`.
     https://docs.wajub.com/developer-tools/webhooks/events
  •  Sandbox scenario
     A sandbox number ending in 000000 succeeds: this outcome is the scenario you chose, not a bug.
     https://docs.wajub.com/developer-tools/testing/test-scenarios
  ✓  The payer paid

Ce qu'elle prend

Un seul argument : un identifiant tiré d'une réponse, d'un webhook ou du Dashboard, ou votre propre référence.

Vous passezLa CLI lit
Un paiement, trx_…Le paiement, ses événements, ses remboursements et vos endpoints de webhook
Un transfert, po_…Le transfert, ses événements et vos endpoints de webhook
Un remboursement, rfd_…Le remboursement et sa chronologie
Un événement, evt_…L'événement, et ceux de vos endpoints qui reçoivent son type
L'identifiant d'un endpoint de webhookL'endpoint : s'il est activé, et à quoi il est abonné
Votre propre referenceLe paiement le plus récent qui la porte, sinon le transfert qui la porte

Un identifiant de sandbox contient test_, comme trx_test_…. Quand l'identifiant et votre clé appartiennent à des environnements différents, la commande le dit avant tout appel, puisque l'API ne répondrait que 404.

Un identifiant live lu avec une clé de sandbox
$ wajub debug trx_CSUGajfv9xh0XQ5wu2lx

Payment trx_CSUGajfv9xh0XQ5wu2lx  (sandbox)
This id belongs to live, and you are using a sandbox key

Diagnosis
  ✗  This id belongs to live, and you are using a sandbox key  [your integration]
     trx_CSUGajfv9xh0XQ5wu2lx was created in live (its id has no `test_`), and the key in use is a sandbox key. The two share no data: the API answers 404.
     → Use a live key: `--profile <live-profile>` or WAJUB_API_KEY=sk.…. If your server reads this id with the same key, it has the same problem.
     https://docs.wajub.com/getting-started/environments

Une référence que portent plusieurs paiements fait expliquer le plus récent et liste les autres. L'identifiant d'une livraison de webhook (whd_…) ou d'une requête API ne se lit pas par l'API : la commande le dit et vous envoie dans Konsole, où Webhooks et Logs API les affichent.

Ce qu'elle affiche

Les deux premières lignes nomment l'objet, son statut et son environnement, puis le problème le plus sérieux trouvé, ou l'état de l'objet quand rien ne va de travers. Timeline, en UTC, suit l'objet depuis sa création : chaque événement avec l'accusé de réception de vos endpoints ou son absence, les remboursements, l'expiration d'un paiement en attente, la dernière mise à jour.

Diagnosis liste les constats, ceux à corriger en premier.

MarqueSignification
✗Un problème à corriger
!À regarder, sans rien bloquer
•Une information, comme le scénario de sandbox choisi par un numéro de test
✓Ce qui s'est passé comme prévu

À côté d'un problème, les crochets disent qui doit agir : [the payer] (le payeur), [the operator] (l'opérateur), [your account settings] (les réglages de votre compte), [Wajub] ou [your integration] (votre intégration). Dessous viennent le détail, l'étape suivante après →, et la page de documentation. Une dernière ligne, Related:, liste les identifiants qui méritent leur propre wajub debug, comme les remboursements d'un paiement.

Ce qu'elle reconnaît

  • Paiements. Un échec côté payeur (fonds insuffisants, un plafond, un code PIN refusé, aucune confirmation à temps) ou de votre côté (un numéro que l'opérateur ne connaît pas, un code généré par le payeur qui manque), et un code d'opérateur que la CLI ne connaît pas, laissé à l'opérateur. Un paiement en attente dont la dernière tentative a été refusée, un paiement expiré avant que le payeur atteigne le checkout, un paiement réussi qu'aucun endpoint ne signale, un callback sur localhost, deux paiements payés avec la même référence, des remboursements échoués, et le scénario choisi par un numéro de test de la sandbox.
  • Transferts et remboursements. Chaque failure_reason des motifs d'échec, avec ce qu'il faut faire, et ce que signifient review et processing pendant que vous attendez.
  • Webhooks. Aucun endpoint dans cet environnement, tous les endpoints désactivés, aucun endpoint abonné à l'événement, un motif comme payment.* qui ne correspond à rien, un endpoint en http:// simple, et un événement que votre endpoint n'a pas acquitté, qu'il soit encore en cours de livraison, en échec ou abandonné après 72 heures, avec wajub events resend pour le rejouer.
  • La mauvaise clé. Un identifiant d'un environnement lu avec une clé de l'autre.

Les règles sont fixes et s'exécutent dans la CLI : les mêmes réponses donnent toujours le même diagnostic, et rien n'est envoyé à un modèle.

Dans les scripts et les agents de développement

--json renvoie le diagnostic : id, kind, found, environment, status, summary, timeline, related, l'objet tel que l'API l'a renvoyé, et findings. Chaque constat porte un code stable sur lequel brancher votre logique, une severity (error, warning, info ou ok), une cause (integration, payer, provider, account, wajub, none ou unknown), un title et, quand il les a, detail, next et docs.

Seulement ce qu'il faut corriger
$ wajub debug trx_test_CSUGajfv9xh0XQ5wu2lx --json | jq -r '.findings[] | select(.severity == "error") | .code'
payment.no_fulfilment_signal
webhook.not_subscribed

La commande se termine avec le code 0 quand elle a trouvé l'objet, quel que soit son état, et 1 quand elle n'a rien trouvé pour l'identifiant, y compris un identifiant de l'autre environnement.

La clé qu'elle utilise

La même clé et la même adresse d'API que toutes les autres commandes : le profil par défaut, ou --profile, WAJUB_API_KEY et --api-base. Utilisation avancée donne l'ordre dans lequel la CLI choisit la clé. Utilisez une clé secrète ou restreinte : une clé publiable (pk.) ne peut pas lire les paiements. Pour un objet ancien, la chronologie peut manquer certains de ses événements ; la commande le signale alors et renvoie au flux d'événements de Konsole.

Que pensez-vous de ce contenu ?