ACP Checkout

Zeodyn™ implements the Agentic Commerce Protocol (ACP) to enable AI agents to purchase subscriptions on behalf of their users. Agents create checkout sessions, provide payment via Stripe SharedPaymentTokens, and receive instant digital fulfilment.

Discovery

The ACP manifest is available at the standard well-known path:

GET https://zeodyn.com/.well-known/acp/config.json

The manifest contains the product catalogue, accepted payment providers, currency, and checkout endpoint URLs. Agents should fetch this manifest to discover available products before creating a checkout.

Authentication

All ACP endpoints require authentication via a Zeodyn API key. Pass it as a Bearer token in the Authorization header:

Authorization: Bearer zd_live_xxxxx

Create an API key from your account settings. Keys use the zd_live_ prefix.

Available products

All prices are in GBP. Amounts in API responses are in minor currency units (pence). See the pricing page for full feature comparisons.

Endpoints

Five endpoints manage the full checkout lifecycle:

Checkout lifecycle

A checkout session progresses through these statuses:

1. Create — POST to /api/acp/checkouts with items and optionally buyer details. Status starts as ready_for_payment.
2. Update (optional) — PUT to change items or buyer info. Buyer email is required before completing — provide it at creation or via update.
3. Complete — POST to /api/acp/checkouts/{id}/complete with a Stripe SharedPaymentToken. Requires buyer email to be set. Status transitions to in_progress, then completed.
4. Cancel (alternative) — POST to cancel instead of completing.

Digital fulfilment is instant — upon successful completion, the user’s account is upgraded immediately and they can access all tier features from the dashboard.

Request examples

Create a checkout

curl -X POST https://zeodyn.com/api/acp/checkouts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zd_live_xxxxx" \
  -d '{
    "items": [
      { "id": "scanner_pro", "quantity": 1 }
    ],
    "buyer": {
      "first_name": "Example",
      "last_name": "Agent",
      "email": "user@example.com"
    }
  }'

Response (201):

{
  "id": "acp_cs_a1b2c3d4e5f6",
  "status": "ready_for_payment",
  "currency": "gbp",
  "line_items": [
    {
      "id": "scanner_pro",
      "name": "Zeodyn Scanner Pro",
      "description": "Unlimited scans, trend charts, PDF export, AI recommendations, API access",
      "quantity": 1,
      "base_amount": 1900,
      "discount": 0,
      "subtotal": 1900,
      "tax": 0,
      "total": 1900
    }
  ],
  "fulfillment_options": [
    { "type": "digital", "id": "instant_access", "title": "Instant Digital Access", "subtitle": "Immediate access upon payment", "subtotal": 0, "tax": 0, "total": 0 }
  ],
  "fulfillment_option_id": "instant_access",
  "payment_provider": { "provider": "stripe", "supported_payment_methods": ["card"] },
  "totals": [
    { "label": "Subtotal", "amount": 1900 },
    { "label": "Total", "amount": 1900 }
  ],
  "buyer": { "first_name": "Example", "last_name": "Agent", "email": "user@example.com" },
  "messages": [
    { "type": "info", "content_type": "plain", "content": "Prices exclude VAT. VAT may apply based on your location." }
  ],
  "links": {
    "terms_of_use": "https://zeodyn.com/legal/terms",
    "privacy_policy": "https://zeodyn.com/legal/privacy"
  }
}

Retrieve a checkout

curl https://zeodyn.com/api/acp/checkouts/acp_cs_a1b2c3d4e5f6 \
  -H "Authorization: Bearer zd_live_xxxxx"

Update a checkout

curl -X PUT https://zeodyn.com/api/acp/checkouts/acp_cs_a1b2c3d4e5f6 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zd_live_xxxxx" \
  -d '{
    "items": [
      { "id": "scanner_growth", "quantity": 1 }
    ]
  }'

Updates are only allowed when the status is not_ready_for_payment or ready_for_payment.

Complete a checkout

curl -X POST https://zeodyn.com/api/acp/checkouts/acp_cs_a1b2c3d4e5f6/complete \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zd_live_xxxxx" \
  -d '{
    "shared_payment_token": "spt_1abc2def3ghi"
  }'

On success, the response includes an order object with the subscription status and dashboard link:

{
  "id": "acp_cs_a1b2c3d4e5f6",
  "status": "completed",
  "order": {
    "id": "ord_a1b2c3d4e5f6",
    "status": "active",
    "permalink": "https://zeodyn.com/dashboard",
    "messages": [
      "Your Zeodyn Scanner Pro subscription is now active.",
      "Sign in at https://zeodyn.com/auth/signin using your email to access your dashboard."
    ]
  }
}

Cancel a checkout

curl -X POST https://zeodyn.com/api/acp/checkouts/acp_cs_a1b2c3d4e5f6/cancel \
  -H "Authorization: Bearer zd_live_xxxxx"

SharedPaymentTokens

Agents provide payment using Stripe SharedPaymentTokens (SPTs). These tokens are created by the agent’s payment infrastructure and passed to the /complete endpoint.

• SPTs are single-use and tied to a specific payment amount
• The token must be valid and unused at the time of completion
• Use the optional idempotency_key field to prevent duplicate payments

For more details on SharedPaymentTokens, see the Stripe documentation.

Error handling

ACP endpoints return standard HTTP status codes with JSON error bodies:

{
  "type": "conflict",
  "code": "checkout_not_modifiable",
  "message": "Checkout session has already been completed."
}

Digital fulfilment

All Zeodyn products are delivered digitally. After a successful /complete call:

• The user’s account is immediately upgraded to the purchased tier
• All tier features (scans, watched sites, API limits, etc.) become available instantly
• The response includes an order.permalink URL for the user to access their dashboard
• A subscription is created with monthly billing from the provisioning date

See also

• Account API — Manage subscriptions and billing via the REST API
• MCP server — Structured tool-based integration for scanning and monitoring
• A2A endpoint — Natural language task interface for agent-to-agent interaction
• ACP specification — Official Agentic Commerce Protocol documentation