ACP Development Patterns
Before writing code
Fetch live docs:
- Checkout spec: Fetch
https://developers.openai.com/commerce/specs/checkout/ for error codes and idempotency rules
- Production guide: Fetch
https://developers.openai.com/commerce/guides/production/ for operational requirements
- Stripe integration: Web-search
site:docs.stripe.com agentic-commerce for PSP-side patterns
- Changelog: Web-search
site:github.com agentic-commerce-protocol CHANGELOG for latest changes
Pattern: Idempotency
Every POST request MUST include Idempotency-Key (UUID v4, max 255 chars).
Server-side implementation:
- Store key → response mapping for minimum 24 hours
- Same key + identical body = replay original response, add
Idempotent-Replayed: true header
- Same key + different body = 422
idempotency_conflict
- Key in flight = 409
idempotency_in_flight with Retry-After header
- 5xx responses are NOT cached — retries treated as fresh requests
Client-side implementation:
- Generate UUID v4 for each logical operation
- Reuse the same key when retrying a failed request
- Generate a new key for a genuinely new operation
- Handle 409 by waiting per
Retry-After then retrying
Pattern: Error Handling
ACP uses a flat error structure:
{type, code, message, param}
type: invalid_request | processing_error | service_unavailable
code: Well-known identifier (e.g., idempotency_conflict, invalid_card, rate_limit_exceeded)
message: Human-readable description
param: JSONPath (RFC 9535) to the offending field
Retry strategy:
429 rate_limit_exceeded — Exponential backoff with jitter
409 idempotency_in_flight — Wait per Retry-After header
5xx — Retry with same idempotency key, exponential backoff
4xx (except 429) — Do not retry, fix the request
Pattern: 3D Secure Authentication
When complete returns authentication_required:
- Extract 3DS challenge from the response
- Present challenge to the buyer (redirect or modal)
- Buyer completes authentication
- Call
complete again with authentication_result:
three_ds_cryptogram
electronic_commerce_indicator
transaction_id
version
- Merchant processes the authenticated payment
Handle authentication timeouts and failures gracefully.
Pattern: Request Signing
For request integrity verification:
- Signature header: Base64-encoded signature over canonical JSON body
- Timestamp header: RFC 3339 for freshness validation
- Algorithm: HMAC (Base64-encoded HMAC signature over canonical JSON body)
- Verification: Reconstruct canonical JSON, verify signature, check timestamp within clock-skew window
Pattern: Webhook Delivery
Merchant → Agent webhook best practices:
- Sign EVERY event with HMAC-SHA256
- Include event ID for consumer-side deduplication
- Implement exponential backoff for failed deliveries
- Set reasonable timeouts (5-30 seconds)
- Log delivery attempts and responses
- Queue events if the webhook endpoint is down
- Verify the receiving endpoint uses HTTPS
Pattern: API Versioning
- Always send
API-Version: YYYY-MM-DD header
- Pin to a specific version in your code
- Test against new versions before upgrading
- Handle version-specific response shape differences
- Log the version used for debugging
Pattern: Rate Limiting
- Implement server-side rate limiting per API key
- Return 429 with
Retry-After header when exceeded
- Client-side: Honor
Retry-After, add jitter to prevent thundering herd
- Monitor rate limit proximity and alert before hitting limits
Pattern: Monetary Amount Safety
- ALL amounts as integers in minor currency units
$19.99 = 1999 (cents)
- Never use floating-point for money
- Validate on input and output
- Use language-specific money libraries (e.g.,
decimal in Python, BigInt in JS)
Pattern: Monitoring & Observability
- Log every checkout operation with session ID and status
- Track conversion funnel: create → update → complete → order
- Alert on error rate spikes (especially 5xx)
- Monitor idempotency key reuse patterns
- Track payment success/failure rates
- Dashboard SPT provisioning and consumption
- Monitor webhook delivery success rates
Pattern: Security Checklist
- TLS 1.2+ on all endpoints
- Bearer token rotation strategy
- No PCI data in logs (redact card numbers, CVCs)
- IP allowlisting for agent platform connections
- Request signing for integrity verification
- HMAC verification on all incoming webhooks
- Rate limiting to prevent abuse
- Input validation on all fields
- CORS configuration (if browser-facing)
Fetch the latest spec and production guide for current error codes, header requirements, and security recommendations before implementing.
1---2name: acp-dev-patterns3description: Cross-cutting ACP development patterns — idempotency, error handling, 3D Secure flows, request signing, rate limiting, monitoring, and security best practices. Use when designing architecture or solving production concerns.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/acp-dev-patterns7---89# ACP Development Patterns1011## Before writing code1213**Fetch live docs**:14- Checkout spec: Fetch `https://developers.openai.com/commerce/specs/checkout/` for error codes and idempotency rules15- Production guide: Fetch `https://developers.openai.com/commerce/guides/production/` for operational requirements16- Stripe integration: Web-search `site:docs.stripe.com agentic-commerce` for PSP-side patterns17- Changelog: Web-search `site:github.com agentic-commerce-protocol CHANGELOG` for latest changes1819## Pattern: Idempotency2021Every POST request MUST include `Idempotency-Key` (UUID v4, max 255 chars).2223**Server-side implementation**:24- Store key → response mapping for minimum 24 hours25- Same key + identical body = replay original response, add `Idempotent-Replayed: true` header26- Same key + different body = 422 `idempotency_conflict`27- Key in flight = 409 `idempotency_in_flight` with `Retry-After` header28- 5xx responses are NOT cached — retries treated as fresh requests2930**Client-side implementation**:31- Generate UUID v4 for each logical operation32- Reuse the same key when retrying a failed request33- Generate a new key for a genuinely new operation34- Handle 409 by waiting per `Retry-After` then retrying3536## Pattern: Error Handling3738ACP uses a flat error structure:39```40{type, code, message, param}41```4243- `type`: `invalid_request` | `processing_error` | `service_unavailable`44- `code`: Well-known identifier (e.g., `idempotency_conflict`, `invalid_card`, `rate_limit_exceeded`)45- `message`: Human-readable description46- `param`: JSONPath (RFC 9535) to the offending field4748**Retry strategy**:49- `429 rate_limit_exceeded` — Exponential backoff with jitter50- `409 idempotency_in_flight` — Wait per `Retry-After` header51- `5xx` — Retry with same idempotency key, exponential backoff52- `4xx` (except 429) — Do not retry, fix the request5354## Pattern: 3D Secure Authentication5556When `complete` returns `authentication_required`:57581. Extract 3DS challenge from the response592. Present challenge to the buyer (redirect or modal)603. Buyer completes authentication614. Call `complete` again with `authentication_result`:62 - `three_ds_cryptogram`63 - `electronic_commerce_indicator`64 - `transaction_id`65 - `version`665. Merchant processes the authenticated payment6768Handle authentication timeouts and failures gracefully.6970## Pattern: Request Signing7172For request integrity verification:73- **Signature header**: Base64-encoded signature over canonical JSON body74- **Timestamp header**: RFC 3339 for freshness validation75- **Algorithm**: HMAC (Base64-encoded HMAC signature over canonical JSON body)76- **Verification**: Reconstruct canonical JSON, verify signature, check timestamp within clock-skew window7778## Pattern: Webhook Delivery7980Merchant → Agent webhook best practices:81- Sign EVERY event with HMAC-SHA25682- Include event ID for consumer-side deduplication83- Implement exponential backoff for failed deliveries84- Set reasonable timeouts (5-30 seconds)85- Log delivery attempts and responses86- Queue events if the webhook endpoint is down87- Verify the receiving endpoint uses HTTPS8889## Pattern: API Versioning9091- Always send `API-Version: YYYY-MM-DD` header92- Pin to a specific version in your code93- Test against new versions before upgrading94- Handle version-specific response shape differences95- Log the version used for debugging9697## Pattern: Rate Limiting9899- Implement server-side rate limiting per API key100- Return 429 with `Retry-After` header when exceeded101- Client-side: Honor `Retry-After`, add jitter to prevent thundering herd102- Monitor rate limit proximity and alert before hitting limits103104## Pattern: Monetary Amount Safety105106- ALL amounts as integers in minor currency units107- `$19.99` = `1999` (cents)108- Never use floating-point for money109- Validate on input and output110- Use language-specific money libraries (e.g., `decimal` in Python, `BigInt` in JS)111112## Pattern: Monitoring & Observability113114- Log every checkout operation with session ID and status115- Track conversion funnel: create → update → complete → order116- Alert on error rate spikes (especially 5xx)117- Monitor idempotency key reuse patterns118- Track payment success/failure rates119- Dashboard SPT provisioning and consumption120- Monitor webhook delivery success rates121122## Pattern: Security Checklist123124- TLS 1.2+ on all endpoints125- Bearer token rotation strategy126- No PCI data in logs (redact card numbers, CVCs)127- IP allowlisting for agent platform connections128- Request signing for integrity verification129- HMAC verification on all incoming webhooks130- Rate limiting to prevent abuse131- Input validation on all fields132- CORS configuration (if browser-facing)133134Fetch the latest spec and production guide for current error codes, header requirements, and security recommendations before implementing.