AP2 Credentials Provider Implementation
Before writing code
Fetch live docs:
- Fetch
https://ap2-protocol.org/specification/ for Credentials Provider responsibilities
- Web-search
site:github.com google-agentic-commerce AP2 samples roles credentials_provider for reference implementation
- Web-search
site:github.com google-agentic-commerce AP2 credentials provider tokenization DPAN for tokenization details
- 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:
- Stores payment credentials — User's payment methods (cards, wallets)
- Provides payment method listings — Returns available methods to Shopping Agent
- Handles tokenization — Converts real credentials to DPANs (Digitized Primary Account Numbers)
- Validates Payment Mandates — Verifies user authorization before releasing tokens
- Facilitates payment — Provides credentials to Merchant Payment Processor
- 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.