Agent Commerce API
A programmatic interface for orchestrating agent settlement workflows, retrieving transaction event history, and accessing verification records. API-first, audit-ready, and designed for autonomous system integration.
Overview
The Agent Commerce API covers the full lifecycle of an agent-initiated financial action - from authorization request through settlement execution to evidence retrieval. It is a REST API that returns structured JSON. Authentication uses API keys. Events are delivered via webhooks.
Authorization
policy evaluation and approval routing
Settlement
provider execution orchestration
Events
full lifecycle event history
Verification
provenance record retrieval
Authentication
All requests require an API key passed in the Authorization header. API keys are scoped to your organization.
Create and manage API keys in your dashboard: /dashboard/cdp/api-keys
Key endpoint categories
Full endpoint reference with request/response schema will be published in the docs system. Contact us for early API access.
Transaction lifecycle
Each transaction progresses through defined states. Every state transition generates a webhook event.
Events and webhooks
Configure your webhook endpoint in the dashboard. All events include event_type, transaction_id, timestamp (ISO-8601), actor identity, status, and metadata.
authorization.requestedauthorization.approvedauthorization.escalatedauthorization.human_approvedauthorization.rejectedexecution.initiatedexecution.succeededexecution.failedreceipt.issuedVerification records
For completed actions, the API exposes receipt and provenance data:
Returns: receipt hash, issuer, algorithm, timestamp, provider reference, and where implemented, a signed provenance artifact verifiable against CertifiedData's public certificate infrastructure.
Verify a record via the verification surface →Integration patterns
Agent authorization request
Your agent calls the authorization endpoint before triggering a financial action. Agent Commerce evaluates policy and routes to approval if required before responding with authorization status.
Webhook-driven architecture
Build event-driven workflows using the webhook delivery system. Each lifecycle state change triggers a delivery to your configured endpoint. Retry semantics and idempotency keys are supported.
Audit log retrieval
Pull the full event history for any transaction at any time via the audit API. Useful for internal review, dispute handling, and governance reporting.
Open source SDK and contract
The Agent Commerce public repo contains the OpenAPI contract, AsyncAPI event schema, Python and TypeScript SDKs, a mock server for local development, and Ed25519 test vectors. Use it to integrate without needing a platform account.
Agent Commerce API - machine-readable surface contract
{
"term": "Agent Commerce API",
"concept_type": "api-surface",
"canonical_url": "https://certifieddata.io/agent-commerce/api",
"api_authentication": {
"scheme": "Bearer",
"header": "Authorization: Bearer <api_key>",
"key_format": "cdp_live_<hex> | cdp_test_<hex>",
"scopes": [
"payments:write",
"payments:read",
"receipts:read",
"webhooks:manage"
],
"note": "API key identifies the calling system — it does not authorize any individual payment. Payment authorization is a separate per-transaction decision."
},
"payment_authorization": {
"schema_version": "payment_authorization.v1",
"decision_values": [
"authorized",
"blocked",
"needs_review"
],
"request_fields": {
"amount_cents": "integer — requested payment amount in the smallest currency unit",
"currency": "ISO-4217 — e.g. USD, EUR",
"merchant_id": "opaque merchant identifier — never a display name",
"purpose_tag": "declared intent category used for policy matching",
"delegated_authority": "optional — agent identifier when acting on behalf of a principal",
"expiration_iso": "ISO-8601 — authorization window; request rejected if evaluated after this"
},
"decision_fields": {
"authorization_id": "auth_{hex} — unique stable identifier for this decision",
"decision": "authorized | blocked | needs_review",
"policy_id": "policy evaluated to produce the decision",
"policy_hash": "SHA-256 of policy JSON at evaluation time — proves which version was active",
"reason_code": "populated when decision is blocked or needs_review",
"created_at": "ISO-8601 UTC timestamp of the authorization decision"
},
"approval_payload": "CDP_CANONICAL_AUTHORIZATION — see cdp-protocol.ts",
"denial_payload": {
"authorization_id": "auth_{hex}",
"decision": "blocked",
"reason_code": "AMOUNT_EXCEEDS_LIMIT | MERCHANT_BLOCKED | PURPOSE_NOT_PERMITTED | EXPIRED"
},
"endpoint": "POST /api/cdp/authorize"
},
"endpoint_categories": [
"Payment authorization",
"Settlement events",
"Approval workflows",
"Transaction history",
"Verification records",
"Webhooks"
],
"lifecycle_states": [
"initiated",
"evaluating",
"needs_review",
"authorized",
"executed",
"receipt_issued",
"rejected"
],
"webhook_events": [
"authorization.requested",
"authorization.approved",
"authorization.escalated",
"authorization.human_approved",
"authorization.rejected",
"execution.initiated",
"execution.succeeded",
"execution.failed",
"receipt.issued"
],
"capture_and_receipt": {
"trigger": "Automatic on authorized + execution.succeeded",
"schema_version": "payment_receipt.v1",
"endpoint": "GET /api/cdp/receipts/{transaction_id}",
"receipt_payload": "CDP_CANONICAL_RECEIPT — see cdp-protocol.ts"
},
"verification_endpoint": "GET /api/cdp/receipts/{transaction_id}",
"public_key": "GET /.well-known/certifieddata.json",
"openapi_reference": "certifieddata-payments-public/openapi/"
}