# 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.

> [!NOTE]
> **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.

```bash title="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 passez                            | La 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 webhook | L'endpoint : s'il est activé, et à quoi il est abonné                       |
| Votre propre `reference`               | Le 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`.

```bash title="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](https://docs.wajub.com/fr/developer-tools/konsole/webhook-tester) et
[Logs API](https://docs.wajub.com/fr/developer-tools/konsole/log-explorer) 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.

| Marque | Signification                                                              |
| ------ | -------------------------------------------------------------------------- |
| `✗`    | 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](https://docs.wajub.com/fr/api/failure-reasons), 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`.

```bash title="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](https://docs.wajub.com/fr/developer-tools/cli/advanced#environment-variables) 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](https://docs.wajub.com/fr/developer-tools/konsole/event-stream) de Konsole.

- [Dépannage des webhooks](https://docs.wajub.com/fr/resources/troubleshooting/webhooks): Les raisons habituelles pour lesquelles un endpoint n'acquitte pas un événement.
- [Dépannage des paiements](https://docs.wajub.com/fr/resources/troubleshooting/payments): Paiements échoués, en attente et expirés, et ce qu’il faut faire.
- [Scénarios de test](https://docs.wajub.com/fr/developer-tools/testing/test-scenarios): Les numéros de sandbox derrière chaque résultat.
- [Recevoir des webhooks en local](https://docs.wajub.com/fr/developer-tools/cli/listen): Reproduisez une livraison en échec sur votre machine.
