Package com.tnsai.payment

Interface PaymentBroker

All Known Implementing Classes:

NoOpPaymentBroker

public interface PaymentBroker

Settlement bus for agent-to-agent payments (TNS-298). Brokers wrap an underlying payment rail (x402, Stripe, Lightning Network, an internal credit ledger) and expose the same two-phase contract: quote prices the work, settle actually moves funds.

Why a broker

Inside a single trust boundary (one tenant, one process group) agents don't need to settle in real money — a NoOpPaymentBroker lets the framework's accountability machinery thread through untouched. Across trust boundaries (cross-tenant, cross-org, decentralized agent economy) the same SPI plugs into a real rail.

Implementations

• NoOpPaymentBroker — quotes at 0.00 USD, all settlements succeed instantly. Default for internal multi-agent.
• X402PaymentBroker (follow-up) — HTTP 402-based micropayment over the agent economy stack.
• StripePaymentBroker (follow-up) — credit-card-backed settlement for human-paid agent services.

Idempotency

Callers MUST supply a Service.metadata-derived idempotency key when they construct the Quote via quote(com.tnsai.identity.AgentPrincipal, com.tnsai.identity.AgentPrincipal, com.tnsai.payment.Service); the broker echoes it on Quote.idempotencyKey so retried settle(com.tnsai.payment.Quote) calls land on the same payment instead of double-charging.

Since:

0.10.0 (TNS-298)

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	PaymentBroker.QuoteRejectedException	Thrown by quote(com.tnsai.identity.AgentPrincipal, com.tnsai.identity.AgentPrincipal, com.tnsai.payment.Service) when broker policy refuses to price.

Method Summary

Modifier and Type	Method	Description
static PaymentBroker	noOp()	Returns the null-object broker: quotes at 0.00 USD, settlements succeed instantly.
Quote	quote(AgentPrincipal payer, AgentPrincipal payee, Service service)	Compute the price for service between payer and payee, returning a Quote the caller can later settle (within Quote.expiresAt).
Settlement	settle(Quote quote)	Move funds for quote.

Method Details

noOp

static PaymentBroker noOp()

Returns the null-object broker: quotes at 0.00 USD, settlements succeed instantly. Used when tnsai-payments is off the classpath — same shape as ContextManagerHandle.noOp() and FeedbackCollector.noOp().

Returns:

a no-op PaymentBroker (singleton)

quote

Quote quote(AgentPrincipal payer,
 AgentPrincipal payee,
 Service service)

Compute the price for service between payer and payee, returning a Quote the caller can later settle (within Quote.expiresAt).

Throws:

NullPointerException - if any arg is null

PaymentBroker.QuoteRejectedException - when broker policy refuses to quote (payer blocked, payee unverified, …); message is operator-actionable

settle

Settlement settle(Quote quote)

Move funds for quote. Idempotent: a second call with the same Quote.idempotencyKey returns Settlement.AlreadySettled instead of double-charging.

Throws:

NullPointerException - if quote is null