acp-dev-patterns

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:

1. Extract 3DS challenge from the response
2. Present challenge to the buyer (redirect or modal)
3. Buyer completes authentication
4. Call complete again with authentication_result:
   • three_ds_cryptogram
   • electronic_commerce_indicator
   • transaction_id
   • version
5. Merchant processes the authenticated payment