Request Trace and Observability

A payment question like "why did it end this way?" is rarely answered by a single field. Request and trace identifiers let you combine routing plans, charge attempts, and event records on the same payment.

Request and trace

Field	Usage
`request_id`	Tags a single API call (for example, one confirm)
`trace_id`	Reads steps in the same workflow together

These fields are for correlation; they do not authenticate or carry secrets. They should not be logged alongside PAN or credentials.

What do you correlate after confirm?

Typical questions:

Which confirm request started this payment?
Which provider candidate was tried nth?
Which charge is DECLINED, which is CAPTURED?
Which payment ID did the webhook arrive with?

request_id / trace_id fields in routing plans and event records make this matching easier.

Relationship fields in event records

Field	Purpose
`payment_id`	Primary payment record
`charge_id`	Provider attempt
`checkout_session_id`	Hosted checkout source
`routing_plan_id`	Which plan routed the payment
`refund_id`	Refund flow

Operations and support teams should start with payment_id, then charge_id and the event timeline if needed.

Reading order in the dashboard

Payment status and amount.
Charge list (attempt count, status).
Routing plan (candidate order, current index).
Event list and detail payload (masked).

A redirect result alone is not final proof; close the loop with payment GET or a webhook.

Example correlation (narrative)

Confirm request
  → routing plan is created (request/trace written)
  → charge attempt(s)
  → domain events
  → webhook delivery
  → dashboard shows all of them on the same payment ID

Security

Trace ID is not a security token.
Event payload is for debug; sensitive fields should be masked.
Sandbox trace does not guarantee production behavior; it is for process habit.