Start with the transaction contract, not the transport
Agentic payments APIs need a contract that survives changes in model, orchestrator, payment processor, and settlement rail. The request should identify the principal, acting agent, merchant, order, amount, currency or asset, authority reference, expiry, and idempotency key. Free-form intent may travel alongside those fields, but it must not replace them at the effect boundary.
Separate endpoints or commands for quote, authorize, execute, inspect, refund, and revoke. That separation lets the policy layer reject a proposed effect before a credential is presented and lets operations retrieve state without accidentally repeating a payment.
- Use stable identifiers for principal, agent, mandate, order, attempt, and settlement.
- Treat amount, merchant, asset, expiry, and purpose as typed policy inputs.
- Return a machine-readable reason when an authority check fails.
- Never infer permission from a previous successful call or conversational context.
Expose a state machine instead of a boolean
A response named success is too ambiguous for money movement. The API should distinguish proposed, authorized, submitted, accepted, settled, fulfilled, reversed, refunded, disputed, expired, and failed. A card authorization, bank submission, and onchain confirmation are different states even when each upstream provider returns a positive response.
Clients need both the current state and the evidence that justifies it. Include provider references, rail identifiers, observed timestamps, policy version, and the transition that is safe to attempt next. This makes recovery deterministic after timeouts or partial failures.
| State | What it proves | What it does not prove |
|---|---|---|
| Authorized | Policy permitted the exact effect | The rail accepted or settled it |
| Submitted | A request reached the payment adapter | Value moved |
| Accepted | The provider accepted processing | Settlement is final |
| Settled | Rail-specific finality evidence was observed | The product was fulfilled |
| Fulfilled | The merchant delivered the recorded outcome | The outcome cannot be disputed |
Make retries boring and duplicate effects difficult
Agents retry aggressively because they are optimizing for task completion. Networks retry because connections fail. Operators replay messages because queues stall. The payment boundary therefore needs an idempotency record scoped to the principal, authority, merchant, order, and intended effect—not only an arbitrary client string.
A repeated request should return the prior attempt and evidence when the semantic effect is the same. If material fields change under the same key, fail with a conflict. If the prior attempt is uncertain, expose an inspect operation before allowing a new effect. Exactly-once delivery is rarely available end to end; durable deduplication and reconciliation are the practical control.
Return an evidence envelope that other teams can operate
The response envelope should link the authorization decision, payment attempt, settlement proof, merchant receipt, and any fulfillment reference. It should be safe to log without exposing reusable credentials or unnecessary personal data. When a policy blocks a transaction, return the violated constraint and a safe escalation path rather than prompting the model to improvise.
Version the semantic contract independently from the provider adapter. A team should be able to move from cards to bank payments or stablecoins without changing what authorized, settled, refunded, or disputed means to the orchestrator and finance systems.
The best agentic payments API makes the dangerous operation narrow and the resulting evidence easy to inspect.
Source discipline
Primary sources
Product status and protocol behavior are checked against maintainer documentation. Company sources establish what their organizations publish; they do not independently prove adoption or performance.