# Diagnose what went wrong

> Ask the CLI what happened to a payment, a transfer, a refund or an event, who has to act, and what to do next.

`wajub debug` takes an id and explains the object behind it: what happened and when, why it failed
or is stuck, who has to act, and the next step with the docs page that covers it. `wajub explain`
is the same command.

> [!NOTE]
> **If your CLI does not know the command**
>
> An answer of `"debug" is not a wajub command` means your CLI predates it, and
> `npm install -g @wajub/cli` updates it.

```bash title="A paid order your server never heard about"
$ 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
```

## What it takes

One argument: an id from a response, a webhook or the Dashboard, or your own reference.

| You pass              | The CLI reads                                                        |
| --------------------- | -------------------------------------------------------------------- |
| A payment, `trx_…`    | The payment, its events, its refunds and your webhook endpoints      |
| A transfer, `po_…`    | The transfer, its events and your webhook endpoints                  |
| A refund, `rfd_…`     | The refund and its timeline                                          |
| An event, `evt_…`     | The event, and which of your endpoints receive its type              |
| A webhook endpoint id | The endpoint: whether it is enabled, and what it subscribes to       |
| Your own `reference`  | The newest payment that carries it, otherwise the transfer that does |

A sandbox id carries `test_`, as in `trx_test_…`. When the id and your key belong to different
environments, the command says so before calling anything, since the API would only answer `404`.

```bash title="A live id read with a sandbox key"
$ 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
```

A reference that several payments carry explains the newest one and lists the others. A webhook
delivery id (`whd_…`) or an API request id cannot be read through the API: the command says so and
sends you to Konsole, where [Webhooks](https://docs.wajub.com/developer-tools/konsole/webhook-tester) and
[API logs](https://docs.wajub.com/developer-tools/konsole/log-explorer) show them.

## What it prints

The first two lines name the object, its status and its environment, then the most serious problem
found, or the state of the object when nothing is wrong. **Timeline**, in UTC, follows the object
from its creation: each event with whether your endpoints acknowledged it, the refunds, the expiry
of a pending payment, the last update.

**Diagnosis** lists the findings, the ones to fix first.

| Mark | Meaning                                                       |
| ---- | ------------------------------------------------------------- |
| `✗`  | A problem to fix                                              |
| `!`  | Worth a look, without blocking anything                       |
| `•`  | Information, such as the sandbox scenario a test number chose |
| `✓`  | What went as it should                                        |

Beside a problem, the brackets say who has to act: `[the payer]`, `[the operator]`,
`[your account settings]`, `[Wajub]` or `[your integration]`. Under it come the details, the next
step after `→`, and the docs page. A last line, `Related:`, lists the ids worth a `wajub debug` of
their own, such as the refunds of a payment.

## What it recognises

- **Payments.** A failure on the payer's side (insufficient funds, a limit, a refused PIN, no
  confirmation in time) or on yours (a number the operator does not know, a missing code the payer
  generates), and an operator code the CLI does not know, kept as the operator's. A pending payment
  whose last attempt was refused, a payment that expired before the payer reached the checkout, a
  succeeded payment no endpoint reports, a callback on `localhost`, two paid payments with the same
  reference, failed refunds, and the scenario a sandbox test number picked.
- **Transfers and refunds.** Every `failure_reason` of the
  [failure reasons](https://docs.wajub.com/api/failure-reasons), with what to do, and what `review` and `processing`
  mean while you wait.
- **Webhooks.** No endpoint in this environment, every endpoint disabled, no endpoint subscribed to
  the event, a pattern such as `payment.*` that matches nothing, a plain `http://` endpoint, and an
  event your endpoint has not acknowledged, whether it is still being delivered, failing, or given
  up after 72 hours, with `wajub events resend` to replay it.
- **The wrong key.** An id from one environment read with a key from the other.

The rules are fixed and run in the CLI: the same answers always give the same diagnosis, and
nothing is sent to a model.

## In scripts and coding agents

`--json` returns the diagnosis: `id`, `kind`, `found`, `environment`, `status`, `summary`,
`timeline`, `related`, the object as the API returned it, and `findings`. Each finding carries a
stable `code` to branch on, a `severity` (`error`, `warning`, `info` or `ok`), a `cause`
(`integration`, `payer`, `provider`, `account`, `wajub`, `none` or `unknown`), a `title`, and,
when it has them, `detail`, `next` and `docs`.

```bash title="Only what needs fixing"
$ wajub debug trx_test_CSUGajfv9xh0XQ5wu2lx --json | jq -r '.findings[] | select(.severity == "error") | .code'
payment.no_fulfilment_signal
webhook.not_subscribed
```

The command exits with status `0` when it found the object, whatever state the object is in, and
`1` when it found nothing for the id, an id from the other environment included.

## Which key it uses

The same key and API address as every other command: the default profile, or `--profile`,
`WAJUB_API_KEY` and `--api-base`.
[Advanced usage](https://docs.wajub.com/developer-tools/cli/advanced#environment-variables) gives the order in which the
CLI picks the key. Use a secret or restricted key: a publishable key (`pk.`) cannot read payments. For an old
object, the timeline may miss some of its events; the command then says so and points to the
[event stream](https://docs.wajub.com/developer-tools/konsole/event-stream) in Konsole.

- [Webhook troubleshooting](https://docs.wajub.com/resources/troubleshooting/webhooks): The usual reasons an endpoint does not acknowledge an event.
- [Payment troubleshooting](https://docs.wajub.com/resources/troubleshooting/payments): Failed, pending and expired payments, and what to do.
- [Test scenarios](https://docs.wajub.com/developer-tools/testing/test-scenarios): The sandbox numbers behind each outcome.
- [Receive webhooks locally](https://docs.wajub.com/developer-tools/cli/listen): Reproduce a failing delivery on your machine.
