orcaqubits/ap2-credentials-provider

AP2 Credentials Provider Implementation

Before writing code

Fetch live docs:

1. Fetch https://ap2-protocol.org/specification/ for Credentials Provider responsibilities
2. Web-search site:github.com google-agentic-commerce AP2 samples roles credentials_provider for reference implementation
3. Web-search site:github.com google-agentic-commerce AP2 credentials provider tokenization DPAN for tokenization details
4. Fetch https://ap2-protocol.org/topics/privacy-and-security/ for security requirements

Conceptual Architecture

What the Credentials Provider Does

The Credentials Provider (CP) is the payment credentials custodian — a digital wallet that securely manages payment methods and handles tokenization:

1. Stores payment credentials — User's payment methods (cards, wallets)
2. Provides payment method listings — Returns available methods to Shopping Agent
3. Handles tokenization — Converts real credentials to DPANs (Digitized Primary Account Numbers)
4. Validates Payment Mandates — Verifies user authorization before releasing tokens
5. Facilitates payment — Provides credentials to Merchant Payment Processor
6. Manages user identity — Links user identity to payment methods

Critical Security Role

The Credentials Provider is the only entity that handles raw payment credentials:

• Shopping Agents never see real card numbers
• Merchants receive only tokenized references
• PCI data stays within the CP's security boundary
• This role-based separation is fundamental to AP2's privacy model

Agent Card

The Credentials Provider advertises:

• AP2 extension support
• Available payment method types
• Tokenization capabilities
• Authentication requirements (OAuth2 recommended)
• Endpoint URL (reference: port 8002, path /a2a/credentials_provider)

Key Responsibilities

Payment Method Management

• Store user payment methods securely (PCI DSS compliance)
• Return available payment methods when queried by Shopping Agent
• Include method details sufficient for user selection (last 4 digits, card type, expiry)
• Never expose full card numbers to Shopping Agents

Tokenization

• Generate DPANs (Digitized Primary Account Numbers) for selected payment methods
• Bind tokens to specific transactions
• Handle token lifecycle (creation, validation, expiration)
• Support network tokenization standards

Payment Mandate Validation

• Receive Payment Mandate + user attestation from Shopping Agent
• Verify user authorization signature
• Verify mandate contents integrity
• Perform additional tokenization if needed
• Release credentials to Merchant Payment Processor upon valid mandate

Credential Release

When the Merchant Payment Processor requests credentials:

• Validate the Payment Mandate
• Resolve the token to real credentials
• Release credentials securely to the MPP
• Never release credentials without a valid Payment Mandate

Payment Method Addition

If a user lacks eligible payment methods:

• CP instructs the Shopping Agent on the setup process
• May require a tokenization flow on CP's trusted surface
• Network/issuer security requirements enforced
• New method added before transaction can proceed

Security Requirements

• PCI DSS compliance for credential storage
• Hardware security modules (HSM) for key management
• Encryption of all credential data at rest and in transit
• Secure token generation with proper entropy
• Rate limiting on credential access
• Audit logging of all credential operations

Best Practices

• Never expose raw credentials to Shopping Agents — always tokenize
• Implement proper PCI DSS controls
• Use hardware-backed token generation
• Validate every Payment Mandate before releasing credentials
• Support multiple payment method types (cards, wallets, bank accounts)
• Implement proper session management for user interactions
• Log all credential access for audit compliance
• Handle token expiration and renewal gracefully

Fetch the specification for exact Credentials Provider API, tokenization requirements, and Payment Mandate validation process before implementing.