Merchant payment detail

Read GET /v1/payments/{id}/detail using a server-held API key with payments:read. Read its state events at GET /v1/payments/{id}/detail/events. Team equivalents use /portal/merchants/{merchant}/payments/{id}/detail and /detail/events, a server-held password-plus-OTP merchant identity and the current X-Futa-Membership-Version. Every request checks current access and merchant quota. Do not expose credentials to browser JavaScript.

Both routes are available in the sandbox profile. The detail contains the exact payment reference, state, creation time, currency, original amount, selected synthetic method, available masked payer identifier, financial snapshot and explicit settlement attribution. Amounts are decimal strings in minor units: use BigInt for arithmetic. Synthetic merchant fees are zero. Collected amount is backed by the payment’s ledger credit; completed and reserved refunds are separate. net_after_refunds subtracts completed refunds and is not an available settlement balance. Settlement batch_id is currently null because aggregate batches have no per-payment allocation. NOT_RETAINED means no identifier was retained; never reconstruct it.

Events are ordered by sequence, with at most 25 per page. Pass the returned next_cursor to /detail/events?cursor={uuid} until it is null. A cursor belongs to one exact payment. A valid cursor after its final event returns an empty page. Events may advance between requests; detail sequence and timeline current_sequence describe separate snapshots. These reads do not initiate or retry a payment and do not replace immutable creation receipts.

Requests accept no body, encoding, extra query parameters or caller X-Futa-* authority headers other than the team membership version. Responses and errors are private and use no-store. Missing or foreign payments/cursors return 404; missing scope or membership returns 403; changed membership returns 409; quota exhaustion returns 429. Refresh current authority after access changes. Missing financial evidence, malformed upstream projections or unavailable services return 503. An unavailable detail is not a failed payment.

Generated MerchantPaymentDetailsApi methods are readPaymentDetail, readPaymentTimeline, readTeamPaymentDetail, and readTeamPaymentTimeline. They preserve nullable identifiers/cursors, money strings and date fields, and do not retry automatically. Generated TypeScript types are not a runtime validator; the merchant service validates its bounded switch responses. Actual FR/EN portal presentation and real provider/fee/settlement allocation remain separate work.