adk-payments

Protocol-neutral agentic commerce and payment orchestration for ADK-Rust.

adk-payments gives you one canonical commerce kernel and durable transaction journal that can sit behind multiple protocol adapters. It is built for cases where an agent needs to create, update, authorize, complete, and follow up on real commerce transactions without leaking raw payment artifacts into normal conversation state.

Overview

Use adk-payments when you need to:

• expose merchant checkout or delegated-payment APIs over ACP
• handle AP2 mandate-based shopper flows with explicit authorization artifacts
• keep one canonical transaction record even when ACP and AP2 are both enabled
• store raw mandates, signatures, tokens, and receipts as evidence instead of transcript text
• preserve transaction continuity after context compaction through durable journal state plus masked memory

The crate combines:

• a canonical commerce domain model in domain
• backend-facing kernel service traits in kernel
• a durable journal + evidence layer in journal
• protocol adapters in protocol::acp and protocol::ap2
• agent-facing payment tools in tools
• server wiring helpers in server

Which Protocol Should I Use?

• Start with ACP stable if you want merchant-hosted HTTP checkout routes and delegated payment support.
• Use ACP experimental only when you need the evolving discovery, delegate-authentication, or webhook extensions and can tolerate draft churn.
• Use AP2 if your flow is mandate-based and involves multiple commerce actors such as shopper, merchant, credentials-provider, and payment-processor.
• Run both ACP and AP2 if you need standards compatibility on multiple fronts but want one backend transaction model.

Protocol Support

ACP stable is the conservative production baseline. AP2 support tracks the current alpha research draft. The experimental ACP surface is intentionally feature-gated because the wire format is still moving.

Installation

Choose only the features you need:

[dependencies]
adk-payments = { version = "0.5.0", features = ["acp"] }

[dependencies]
adk-payments = { version = "0.5.0", features = ["ap2", "ap2-a2a", "ap2-mcp"] }

[dependencies]
adk-payments = { version = "0.5.0", features = ["acp", "acp-experimental", "ap2"] }

Core Concepts

Canonical Transaction

ACP sessions, ACP orders, AP2 mandates, and AP2 receipts all correlate to one internal TransactionId. Protocol IDs are preserved in ProtocolRefs; they are not treated as interchangeable.

Durable Journal

The transaction journal stores canonical commerce state in adk-session. Safe, masked transaction summaries are indexed into adk-memory. Raw sensitive payloads live in adk-artifact through the evidence store.

Evidence First

Raw payment credentials, merchant signatures, user authorizations, mandate payloads, and receipt bodies are preserved as immutable evidence artifacts. Only safe summary metadata is kept in transcript-visible and memory-visible surfaces.

Kernel-Mediated Compatibility

ACP and AP2 can share a backend, but adk-payments does not pretend their artifacts are semantically equivalent. When a direct ACP-to-AP2 or AP2-to-ACP conversion would lose provenance or authorization semantics, the kernel returns an explicit unsupported error instead of fabricating a translation.

Typical Architecture

Agent / Tool / Server surface
        |
        v
   ACP router or AP2 adapter
        |
        v
Canonical commerce kernel traits
        |
        +--> transaction journal (adk-session)
        +--> evidence store (adk-artifact)
        +--> masked recall index (adk-memory)
        +--> auth + guardrail enforcement

Quick Start

1. Expose ACP Checkout Routes

use std::sync::Arc;

use adk_payments::domain::{CommerceActor, CommerceActorRole, CommerceMode, MerchantRef, ProtocolExtensions};
use adk_payments::protocol::acp::{AcpContextTemplate, AcpRouterBuilder, AcpVerificationConfig};

let router = AcpRouterBuilder::new(AcpContextTemplate {
    session_identity: Some(identity),
    actor: CommerceActor {
        actor_id: "shopper-agent".to_string(),
        role: CommerceActorRole::AgentSurface,
        display_name: Some("shopper".to_string()),
        tenant_id: Some("tenant-1".to_string()),
        extensions: ProtocolExtensions::default(),
    },
    merchant_of_record: MerchantRef {
        merchant_id: "merchant-123".to_string(),
        legal_name: "Merchant Example LLC".to_string(),
        display_name: Some("Merchant Example".to_string()),
        statement_descriptor: Some("MERCHANT*EXAMPLE".to_string()),
        country_code: Some("US".to_string()),
        website: Some("https://merchant.example".to_string()),
        extensions: ProtocolExtensions::default(),
    },
    payment_processor: None,
    mode: CommerceMode::HumanPresent,
})
.with_merchant_checkout_service(checkout_service)
.with_delegated_payment_service(delegated_payment_service)
.with_verification(AcpVerificationConfig::strict())
.build()?;

Use this route surface when you want HTTP endpoints for checkout session create, update, completion, cancelation, status lookup, and delegated payment.

2. Handle AP2 Mandate Flows

use adk_payments::protocol::ap2::Ap2Adapter;

let adapter = Ap2Adapter::new(
    checkout_service,
    payment_execution_service,
    transaction_store,
    evidence_store,
)
.with_intervention_service(intervention_service);

let record = adapter.submit_cart_mandate(context, cart_mandate).await?;
let payment = adapter.submit_payment_mandate(context, payment_mandate).await?;
let final_record = adapter.apply_payment_receipt(context, payment_receipt).await?;

Use AP2 when your flow is mandate-based and multiple specialized actors participate in authorization and settlement.

3. Register Agent-Facing Payment Tools

use adk_payments::tools::PaymentToolsetBuilder;

let toolset = PaymentToolsetBuilder::new(checkout_service, transaction_store)
    .with_intervention_service(intervention_service)
    .build();

let tools = toolset.tools();

These tools return masked transaction summaries only. Raw card data, signatures, and authorization blobs do not appear in tool outputs.

Primary Journeys

The crate is currently shaped around five first-class journeys:

• ACP human-present checkout with delegated payment and post-order updates
• AP2 human-present shopper, merchant, credentials-provider, and payment-processor flow
• AP2 human-not-present intent flow with either autonomous completion or forced return-to-user intervention
• dual-protocol backends serving ACP and AP2 against one canonical transaction journal
• post-compaction recall where durable transaction state survives loss of conversational detail

Security Model

• Raw payment credentials, merchant signatures, user authorizations, and receipt artifacts are stored as evidence.
• Session state and semantic memory retain only masked transaction summaries.
• adk-auth binds requests to session identity and audit metadata.
• adk-guardrail enforces amount, merchant, intervention, and protocol-policy checks before persistence.
• The kernel refuses lossy protocol-to-protocol conversions rather than approximating semantics.

Validation and Examples

The integration tests are the authoritative executable reference path:

cargo test -p adk-payments --features acp --test acp_integration_tests
cargo test -p adk-payments --features ap2,ap2-a2a,ap2-mcp --test ap2_integration_tests
cargo test -p adk-payments --test cross_protocol_correlation_tests
cargo test -p adk-payments --features acp-experimental --test acp_experimental_integration_tests

Use these as the starting point for real implementations:

• adk-payments/tests/acp_integration_tests.rs
• adk-payments/tests/ap2_integration_tests.rs
• adk-payments/tests/cross_protocol_correlation_tests.rs
• examples/payments/
• docs/official_docs/security/payments.md

Related Modules

• domain - canonical commerce types
• kernel - protocol-neutral commands, service traits, correlation, and errors
• journal - durable transaction and evidence persistence
• protocol::acp - ACP server and verification surfaces
• protocol::ap2 - AP2 adapter, verification, A2A, and MCP surfaces
• tools - agent-facing checkout, status, and intervention tools
• server - ACP router re-exports and AP2 integration notes