Diagnostics

Every payments milestone emits on the @adonis-agora/diagnostics bus as agora:payments:<event>. The library reads the diagnostics slot structurally — it never imports the package — so when diagnostics isn't installed the emits are inert no-ops, and when it is, everything downstream (Telescope, OTel, custom watchers) lights up at once.

Three layers of events

The catalog spans three layers, and the distinction matters for how you react:

• Gateway-action events fire when your code calls the gateway — charge.created when a charge is created, charge.refunded, subscription.created/canceled, invoice.emitted, invoice.failed. They describe what the app did.

  invoice.failed is the one to subscribe to on day one if you emit fiscal invoices. A failing invoice provider no longer rejects charge() — that reported a failure over money the gateway had already taken, and the obvious response to a failed charge is to charge again. The charge succeeds, the invoice does not, and this event is the only thing that says so. In Brazil an NFS-e is a legal obligation, so a human has to act on it.

• Business events fire when a webhook confirms a state change — payment.succeeded, payment.failed, payment.refunded, payment.disputed, payment.dispute_warning, payment.dispute_closed, payment.updated, subscription.updated. They describe what the gateway says happened. These are the ones webhook handlers and notification flows react to.

• Debug events exist for the developer holding one broken payment, not for a dashboard — gateway.request/gateway.request.failed (what was actually sent to the gateway, what came back, how long it took) and webhook.verification (whether the signature verified, and under which scheme). Nobody subscribes to these in business code; you open them in Telescope when something has already gone wrong.

The runtime catalog is exported as PAYMENTS_DIAGNOSTIC_EVENTS — a single source of truth for watchers and tools that iterate the full list.

Reacting to the business events

The payment.*/subscription.* events are the normalized business surface. Subscribe with onDiagnostic (framework-agnostic — HTTP, workers, ace commands all work):

import { onDiagnostic } from '@adonis-agora/diagnostics'

onDiagnostic('payments', 'payment.succeeded', ({ payload }) => {
  const payment = await Payment.find(payload.externalReference)
  // grant access...
})

How emission works — the structural slot

@adonis-agora/payments never imports @adonis-agora/diagnostics. Instead it reads a well-known process-wide slot:

const EMIT_SLOT = Symbol.for('@agora/diagnostics:emit')

When diagnostics is loaded, it publishes its emit(lib, event, payload) function on that slot; payments calls it structurally. If the slot is empty, the emit is a no-op. The same trick is used for claims (so a lib-specific Telescope watcher can opt channels out of the generic watcher) and for tracing. Zero dependency, zero overhead when nobody listens.

Watching in Telescope

@adonis-agora/telescope ships a generic DiagnosticsWatcher that records every agora:<lib>:<event> publish automatically — no per-library watcher needed. Install telescope and the agora:payments:* entries show up in the timeline as diagnostic entries with the payload preserved.

The typed payments watcher

You do not wire this, and there is nothing to configure. If @adonis-agora/telescope is registered in the app, the payments provider registers the typed watcher and releases it on shutdown. No import, no start/telescope.ts, no option.

Two things could have been options and are detected instead:

• "I wire my own." A watcher claims the payments channels when it registers, so an app that already has one has claimed them before the provider looks, and the provider stands down. Nothing is recorded twice. This is why the registration happens in the provider's ready() rather than boot(): start/ files run first, so your wiring always wins the race.
• "I do not use telescope." Then it is not in the app, and nothing happens. An app without observability is a normal app, not a misconfigured one — it should not fail to boot and it should not be told about it on every start.

A write to the telescope store that fails is swallowed. Recording is observability, and record runs synchronously inside the charge that published the event — a store that is full, locked or briefly unreachable must not take a payment webhook down with it.

PaymentsWatcher and registerPaymentsWatcher are exported from @adonis-agora/payments/telescope if you need to drive one yourself against a second store.

The entry content is shaped, not spread blindly: event, then the correlation id, then the fields you scan a timeline by (provider, gatewayId, id, type, method, host, path, status, outcome, scheme, amount, currency, durationMs, error, reason), then whatever else the payload carried, then ts.

Debugging one payment

The events above tell you a payment succeeded. The two below tell you why one didn't.

What was actually sent to the gateway

Every call made through the shared HTTP transport publishes gateway.request, or gateway.request.failed when it timed out, could not connect, or came back non-2xx:

{
  "event": "gateway.request.failed",
  "traceId": "0f1c…",
  "provider": "asaas",
  "method": "POST",
  "host": "api.asaas.com",
  "path": "/v3/payments",
  "query": "?access_token=[redacted]",
  "status": 422,
  "outcome": "http_error",
  "durationMs": 143,
  "error": "HTTP 422"
}

A timeout and a 422 are the two outcomes worth having, and neither left a trace anywhere before this.

Bodies are opt-in, and off by default

A charge body carries the cardholder's PAN and the payer's CPF/CNPJ, so bodies are not recorded unless you ask:

import { configurePaymentsDiagnostics } from '@adonis-agora/payments'

// Debugging one integration — not a standing production setting.
configurePaymentsDiagnostics({ recordHttpBodies: true })

Turning it on adds requestBody and responseBody to the gateway.request* entries, with every value under a credential, card or tax-document key replaced, long strings truncated and long arrays cut short. Redaction is a key-name heuristic, not a guarantee — turn it on to answer a question, then turn it off.

It is a module-level switch rather than a config/payments.ts key because the HTTP transport that reads it has no access to the app config, and because it is a debugging toggle rather than a deployment setting.

Whether the webhook signature actually verified

webhook.received says a delivery arrived. webhook.verification says what authenticated it:

That last row is the one to read carefully. unreported means one of three things, and the entry deliberately does not guess which:

1. the driver verified inside its own SDK (Stripe's constructEvent does),
2. the gateway signs nothing at all and there is nothing to verify — Efí and InfinitePay, which declare webhookVerification: 'unsupported', or
3. no webhook credential is configured, which requires the provider to be named in allowUnverifiedWebhooks — an app that has not said that refuses to boot.

The third case is a boot error, not a silent default, so this row is a cross-check rather than the only place it shows: unreported plus a driver that is not SDK-based and not one of the two unsigned gateways means somebody wrote an opt-out.

Reading one delivery as one chain

Each webhook delivery attempt gets a traceId, established by the lib-mounted webhook route. Everything the delivery reaches inside that async context carries it — webhook.received → webhook.verification → the business event the built-in handler published → any gateway call your handler made → webhook.processed or webhook.failed. Filter the Telescope timeline by that one id and you have the whole story for that one event, in order.

A redelivery gets its own id, which is what you want when the question is why the retry behaved differently.

Two limits worth knowing, rather than discovering:

• Payments cannot set the envelope's traceId. The structural emit slot is (lib, event, payload), so the id rides on the payload. It should stay that way: @adonis-agora/diagnostics fills DiagnosticEvent.traceId from your app's own request-context accessor, and overwriting that would break correlation with every other Agora library. The watcher merges both, envelope first.
• The chain stops at a process boundary. With dispatcher: 'durable' (or a split role: 'api' / 'worker' deployment) the event is handed to another process, and the trace id is not part of the dispatched job — WebhookEvent has no field for it. The webhook.received/verification half is traced; the processing half is not.

Custom watcher / subscriber

The events are plain node:diagnostics_channel channels, so anything can subscribe:

import { onDiagnostic } from '@adonis-agora/diagnostics'

onDiagnostic('payments', 'charge.created', (event) => {
  console.log('charge created', event.payload)
})