A principal is an individual or business on whose behalf an agent acts. Individuals act for themselves; businesses act through an authorized representative. Identity checks use KYC for individuals and KYB for businesses.
Proposed API contract. Endpoints and example base URLs are not live.
Base URL Placeholder · not live
https://sandbox.agentpay.example/v1
Quickstart
Six steps from agent enrollment to payment capability. First onboard the principal with an authorized session; complete hosted KYC / KYB where required before granting spending authority.
Bind the verified agent to an individual or business principal.
Use a trusted PRINCIPAL session or scoped ADMIN / PARTNER channel. Business consent requires verified representative authority and a spending mandate; an agent-supplied acknowledgment cannot establish either.
Card secrets, if issuance permits them, appear only in the initial issuance response. GET endpoints remain redacted. Issuance does not confirm a completed purchase.
Authentication & access
POST /agents and POST /authenticate are public entry points. Protected endpoints use HTTP Bearer / JWT with AGENT, PRINCIPAL, ADMIN or PARTNER roles.
A PRINCIPAL session is scoped to the represented individual or business. For a business, the service verifies the authenticated representative’s authority and spending mandate. Role eligibility does not replace resource ownership, binding or partner-scope checks. KYC / KYB does not grant spending authority.
Issuer evaluation uses a mutually authenticated issuer / processor channel (mTLS), with explicit partner permission. Ordinary agent bearer tokens cannot call it.
Mutations with an Idempotency-Key parameter require the same key and payload for retries; reuse with a changed payload returns 409. Expand an endpoint for its required headers and parameters.
API reference
All 30 operations, with exact YAML summaries, access requirements, parameters, response codes and linked schemas.
Contract information, servers and shared components
Contract information, servers and shared components
{
"openapi": "3.1.0",
"info": {
"title": "Agent Pay — Public Agent, Principal, Intent and Payment API",
"version": "0.4.1-draft",
"summary": "Individual and business principals, role-scoped onboarding, Know Your Agent, KYC/KYB, intent verification and one-use card issuance",
"description": "PROPOSED DESIGN — contract under discussion, not a deployed service or network certification.\n\nAuthentication uses a single BearerAuth scheme across role-aware protected endpoints.\nRoles: AGENT, PRINCIPAL, ADMIN, PARTNER. Role eligibility is necessary but never\nsufficient: every resource is checked for ownership, principal binding and partner\nportfolio scope. 401 is missing/invalid authentication; 403 is a valid actor denied\nby RBAC/relationship; some unauthorized resource lookups intentionally return 404.\n\nA principal is the individual or business on whose behalf an agent acts. Each\nprincipal has an immutable principal_type of INDIVIDUAL or BUSINESS and a matching\nindividual or business profile. PRINCIPAL is the role of a trusted principal-scoped\nsession: an individual acts for themselves; a business acts through an authenticated,\nauthorized representative. The service verifies that representative's authority and\nspending mandate server-side. A business profile, contact email or consent flag is\nnot proof of authority. ADMIN/PARTNER access remains explicitly tenant/portfolio scoped.\nIdentity verification is KYC for individuals and KYB for businesses, including required\nrepresentative/ownership checks through the trusted provider. It does not grant spending\nauthority. Verification type is determined from principal_type, never chosen by an agent.\n\nPOST /agents is unauthenticated email-based enrollment. Its opaque one-time enrollment\ncredential is bound to the registration session, valid for a short period, held by\nthe caller and cannot be redeemed until a human verifies email and explicitly approves\nthe agent profile in a trusted hosted flow. /authenticate is a single-call endpoint\nfor initial redemption or ongoing signed-assertion / rotated API-key authentication.\nAgent identity, principal KYC/KYB, agent binding, purchase intent verification and issuer\nauthorization are distinct trust boundaries. Identity and payment credentials are not\npermissions to spend. An AI/risk model may inform review/step-up but cannot override\nhard deterministic restrictions. An agent-provided technology/machine/IP claim is not\nproven runtime identity; compare signed/stable credentials and server-observed signals.\n\nPayment capability creation has a system-controlled nominal 60-second initiation\nwindow (not caller configurable). Each virtual-card payment attempt gets a dedicated\nissuer-processor card identifier stored server-side with credential_id, payment_id and\nintent_id. Issuer authorization matches on the processor card identifier (or agreed\nissuer token reference), not name/CVV/expiry. Distinguish authorization retries,\nreversals and captures to enforce one successful purchase per intent. For network-native\nagentic rails, equivalent one-purchase transaction binding requires partner validation.\n\nPOST /intents/{intentId}/pay may return PAN/expiry/CVV one time to an authorized agent\nin the payment issuance response only, contingent on issuer permissions, PCI-compliant\nprocessing and secure delivery. Never persist CVV after authorization, log payment\ncredentials or repeat sensitive card data from GET requests or idempotent replays.\nA gateway token may be PSP-specific and potentially sensitive; do not treat it as an\nissuer correlation reference. Cardholder name uses sponsor-approved alphabetic values,\nnever a primary correlation key. Provisioning credentials does not prove a purchase.\n\nNormal issuer authorization data includes merchant/amount/MCC/country when available,\nbut not reliably SKU, shipping, billing or PSP checkout URL. Verify these separately\nfrom trusted merchant/PSP evidence where possible. All issuer matching/fail-closed\nbehavior, cardholder formats, 3DS timeouts and settlement require bank/PSP validation.\n",
"contact": {
"name": "Agent Pay API design"
}
},
"servers": [
{
"url": "https://api.agentpay.example/v1",
"description": "Placeholder production endpoint, not live"
},
{
"url": "https://sandbox.agentpay.example/v1",
"description": "Placeholder sandbox endpoint, not live"
}
],
"jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
"tags": [
{
"name": "Agents",
"description": "Email-verified enrollment, lifecycle, KYA and principal/agent limits"
},
{
"name": "Authentication",
"description": "Single-request enrollment redemption or credential-based agent authentication"
},
{
"name": "Principals",
"description": "Individual/business onboarding, trusted representation and agent binding"
},
{
"name": "Verification",
"description": "Hosted KYC for individuals and KYB for businesses"
},
{
"name": "Intents",
"description": "Purchase details and verification against principal authorization"
},
{
"name": "Payments",
"description": "Payment capability issuance, status and reversal requests"
},
{
"name": "Issuer Integration",
"description": "Internal issuer/processor-facing, NOT exposed to untrusted agents"
}
],
"security": [],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "Short-lived actor token (roles AGENT, PRINCIPAL, ADMIN or PARTNER). PRINCIPAL scopes an individual session or an authorized representative acting for a business; onboarding additionally requires explicit onboarding authority. Every operation enforces principal binding/ownership, business representative authority and spending mandate where applicable, or explicitly delegated tenant/partner portfolio scope.\n"
},
"IssuerMutualTLS": {
"type": "mutualTLS",
"description": "Mutually authenticated issuer/processor channel; network and processor trust agreements are additionally required."
}
},
"parameters": {
"IdempotencyKey": {
"in": "header",
"name": "Idempotency-Key",
"required": true,
"description": "Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409.",
"schema": {
"type": "string",
"minLength": 16,
"maxLength": 128
}
},
"AgentId": {
"name": "agentId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^agt_[A-Za-z0-9_-]+$"
}
},
"PrincipalId": {
"name": "principalId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^prn_[A-Za-z0-9_-]+$"
}
},
"IntentId": {
"name": "intentId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^int_[A-Za-z0-9_-]+$"
}
},
"PaymentId": {
"name": "paymentId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^pay_[A-Za-z0-9_-]+$"
}
},
"Cursor": {
"name": "cursor",
"in": "query",
"schema": {
"type": "string"
},
"description": "Opaque server-generated pagination cursor"
},
"Limit": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
}
},
"responses": {
"BadRequest": {
"description": "Invalid syntax or input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"Unauthorized": {
"description": "No valid authentication for this actor",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"Forbidden": {
"description": "Authenticated actor lacks rights to the resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"NotFound": {
"description": "Not found or deliberately hidden from this actor",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"Conflict": {
"description": "State conflict, optimistic lock or idempotency mismatch",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"Unprocessable": {
"description": "Well-formed request fails domain or financial validation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"RateLimited": {
"description": "Too many requests",
"headers": {
"Retry-After": {
"description": "Seconds or HTTP date until retry",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"Unavailable": {
"description": "Dependency unavailable; no implicit authorization or approval",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
}
Agents
Email-verified enrollment, lifecycle, KYA and principal/agent limits
POST/agentsStart agent signup with email and declared KYA profile (no bearer token)PUBLIC›
Public enrollment creates a server-generated agent_id in PENDING_EMAIL_VERIFICATION.
A confirmation link is emailed to the address provided. The human must examine and
approve the agent purpose and submitted technical profile; email ownership is not
proof of agent runtime/framework identity. Response includes an opaque short-lived
enrollment credential delivered to the caller only once. It cannot authenticate
until email approval is complete, expires, and can be redeemed only once via
POST /authenticate. No agent_id, operator_id or bearer token is supplied in this body.
Apply bot/rate controls and prevent registration spam and account enumeration.
Authentication
Public · no bearer token
Eligible roles
PUBLIC
Parameters
Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409. · {"type": "string", "minLength": 16, "maxLength": 128}
Retry-After · Seconds or HTTP date until retry · {"type": "string"}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
409 State conflict, optimistic lock or idempotency mismatch
429 Too many requests
Full OpenAPI operation definition
Full OpenAPI operation definition
{
"pathItem": {},
"operation": {
"tags": [
"Agents"
],
"operationId": "registerAgent",
"summary": "Start agent signup with email and declared KYA profile (no bearer token)",
"description": "Public enrollment creates a server-generated agent_id in PENDING_EMAIL_VERIFICATION.\nA confirmation link is emailed to the address provided. The human must examine and\napprove the agent purpose and submitted technical profile; email ownership is not\nproof of agent runtime/framework identity. Response includes an opaque short-lived\nenrollment credential delivered to the caller only once. It cannot authenticate\nuntil email approval is complete, expires, and can be redeemed only once via\nPOST /authenticate. No agent_id, operator_id or bearer token is supplied in this body.\nApply bot/rate controls and prevent registration spam and account enumeration.\n",
"security": [],
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterAgentRequest"
}
}
}
},
"responses": {
"201": {
"description": "Pending agent signup and email confirmation instructions",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentEnrollment"
},
"example": {
"agent_id": "agt_8fd231",
"enrollment_id": "enr_a52e11",
"status": "PENDING_EMAIL_VERIFICATION",
"email_verification_required": true,
"enrollment_credential": "enroll_secret_example_one_time",
"expires_at": "2026-10-08T17:30:00Z",
"message": "Verification email sent. Approve the agent profile before authenticating."
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
},
"x-agentpay-roles": [
"PUBLIC"
]
}
}
GET/agentsList agents bound to the current principal (role-scoped)PRINCIPAL / AGENT / ADMIN / PARTNER›
PRINCIPAL sees lightweight entries for agents bound to their principal account.
AGENT sees its own registered entry unless granted a more specific delegation.
ADMIN sees authorized tenant records, PARTNER sees portfolio-scoped entries.
Always enforce row-level relationship checks and pagination.
Authentication
HTTP Bearer / JWT
Eligible roles
PRINCIPAL, AGENT, ADMIN, PARTNER
Only bound agents or explicitly authorized tenancy/portfolio agents.
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
PUT/agents/{agentId}Update agent configurationAGENT / PRINCIPAL / ADMIN / PARTNER›
Update mutable profile settings. Sensitive verified fields (email, owner,
trusted KYA state, runtime signing keys) require independent owner consent and a
trusted key-rotation workflow. An AGENT may update its own nonprivileged claims,
while owner/ADMIN/PARTNER can change fields allowed by their scope. PUT is treated
as a replacement of the mutable agent profile; omission clears optional profile
fields, never server-managed identity or trusted observations.
Authentication
HTTP Bearer / JWT
Eligible roles
AGENT, PRINCIPAL, ADMIN, PARTNER
Agent self-service only for declared metadata. Bound owner or privileged actor for owner-controlled fields.
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
Request JSON
{
"name": "ShoppingAgent",
"purpose": "Buy books with principal approval"
}
403 Authenticated actor lacks rights to the resource
404 Not found or deliberately hidden from this actor
409 State conflict, optimistic lock or idempotency mismatch
401 No valid authentication for this actor
Full OpenAPI operation definition
Full OpenAPI operation definition
{
"pathItem": {
"parameters": [
{
"$ref": "#/components/parameters/AgentId"
}
]
},
"operation": {
"tags": [
"Agents"
],
"operationId": "updateAgent",
"summary": "Update agent configuration",
"description": "Update mutable profile settings. Sensitive verified fields (email, owner,\ntrusted KYA state, runtime signing keys) require independent owner consent and a\ntrusted key-rotation workflow. An AGENT may update its own nonprivileged claims,\nwhile owner/ADMIN/PARTNER can change fields allowed by their scope. PUT is treated\nas a replacement of the mutable agent profile; omission clears optional profile\nfields, never server-managed identity or trusted observations.\n",
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateAgentRequest"
}
}
}
},
"responses": {
"200": {
"description": "Updated agent",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Agent"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"x-agentpay-roles": [
"AGENT",
"PRINCIPAL",
"ADMIN",
"PARTNER"
],
"x-agentpay-resource-authorization": "Agent self-service only for declared metadata. Bound owner or privileged actor for owner-controlled fields."
}
}
POST/agents/{agentId}/disableDisable an agent and prevent further spendingPRINCIPAL / ADMIN / PARTNER›
Blocks new tokens and capabilities; invalidates active agent sessions/capabilities where operationally possible. Does not unwind already authorized purchases.
Authentication
HTTP Bearer / JWT
Eligible roles
PRINCIPAL, ADMIN, PARTNER
Only verified agent owner or authorized administrator/partner.
Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409. · {"type": "string", "minLength": 16, "maxLength": 128}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409. · {"type": "string", "minLength": 16, "maxLength": 128}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
POST/agents/{agentId}/deleteLogically delete an agentPRINCIPAL / ADMIN / PARTNER›
Soft delete (tombstone), revoke credentials, disable bindings and unused
capabilities. Immutable payment and audit records must be retained where
required. POST is retained as explicitly requested; this is not physical
deletion and cannot be undone by /enable.
Authentication
HTTP Bearer / JWT
Eligible roles
PRINCIPAL, ADMIN, PARTNER
Only verified agent owner or authorized administrator/partner.
Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409. · {"type": "string", "minLength": 16, "maxLength": 128}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
403 Authenticated actor lacks rights to the resource
404 Not found or deliberately hidden from this actor
401 No valid authentication for this actor
Full OpenAPI operation definition
Full OpenAPI operation definition
{
"pathItem": {
"parameters": [
{
"$ref": "#/components/parameters/AgentId"
}
]
},
"operation": {
"tags": [
"Agents"
],
"operationId": "deleteAgent",
"summary": "Logically delete an agent",
"description": "Soft delete (tombstone), revoke credentials, disable bindings and unused\ncapabilities. Immutable payment and audit records must be retained where\nrequired. POST is retained as explicitly requested; this is not physical\ndeletion and cannot be undone by /enable.\n",
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"responses": {
"200": {
"description": "Agent deleted (tombstoned)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Agent"
}
}
}
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"x-agentpay-roles": [
"PRINCIPAL",
"ADMIN",
"PARTNER"
],
"x-agentpay-resource-authorization": "Only verified agent owner or authorized administrator/partner."
}
}
GET/agents/{agentId}/kyaRead the agent Know Your Agent (KYA) assessmentAGENT / PRINCIPAL / ADMIN / PARTNER›
Separate self-declared information, verified operator/key proofs and server-observed runtime/IP risk signals. Sensitive details may be redacted by role.
Authentication
HTTP Bearer / JWT
Eligible roles
AGENT, PRINCIPAL, ADMIN, PARTNER
Self, bound principal or administrative/partner scope.
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
Limits are scoped to the authenticated principal's binding with this agent; a PARTNER or ADMIN must supply the permitted principal_reference where acting on behalf of a principal. Agent self-service cannot create or raise spending authority. All limits cap a separately authenticated principal spending mandate; they do not grant spending authority themselves. Weekly period is a rolling 7 days.
Authentication
HTTP Bearer / JWT
Eligible roles
PRINCIPAL, ADMIN, PARTNER
Bound principal or explicitly authorized principal portfolio.
Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409. · {"type": "string", "minLength": 16, "maxLength": 128}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
403 Authenticated actor lacks rights to the resource
404 Not found or deliberately hidden from this actor
409 State conflict, optimistic lock or idempotency mismatch
Full OpenAPI operation definition
Full OpenAPI operation definition
{
"pathItem": {
"parameters": [
{
"$ref": "#/components/parameters/AgentId"
}
]
},
"operation": {
"tags": [
"Agents"
],
"operationId": "createAgentLimits",
"summary": "Set initial per-principal agent purchase/weekly/total limits",
"description": "Limits are scoped to the authenticated principal's binding with this agent; a PARTNER or ADMIN must supply the permitted principal_reference where acting on behalf of a principal. Agent self-service cannot create or raise spending authority. All limits cap a separately authenticated principal spending mandate; they do not grant spending authority themselves. Weekly period is a rolling 7 days.\n",
"security": [
{
"BearerAuth": []
}
],
"x-agentpay-roles": [
"PRINCIPAL",
"ADMIN",
"PARTNER"
],
"x-agentpay-resource-authorization": "Bound principal or explicitly authorized principal portfolio.",
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetAgentLimitsRequest"
}
}
}
},
"responses": {
"201": {
"description": "Limits established",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentLimits"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
}
}
}
GET/agents/{agentId}/limitsRetrieve current limits and usage for one principal-agent bindingAGENT / PRINCIPAL / ADMIN / PARTNER›
PRINCIPAL scope comes from bearer identity. AGENT must supply a bound principal_reference if bound to more than one principal; only authorized data returned. Outstanding reservations count against spend ceilings.
Authentication
HTTP Bearer / JWT
Eligible roles
AGENT, PRINCIPAL, ADMIN, PARTNER
Bound principal or approved portfolio; no cross-principal leakage.
principal_reference · query · optional — Required for an agent with multiple principal bindings and for privileged delegated reads · {"type": "string"}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
A change to any limit does not authorize spending by itself. Concurrent reservations and already approved intents remain constrained; enforcement uses the strictest applicable principal/issuer/agent ceiling. All changes audited.
Authentication
HTTP Bearer / JWT
Eligible roles
PRINCIPAL, ADMIN, PARTNER
Bound principal or approved portfolio. Agent bearer cannot increase limits.
Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409. · {"type": "string", "minLength": 16, "maxLength": 128}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
Single-request enrollment redemption or credential-based agent authentication
POST/authenticateAuthenticate agent in one call (email enrollment, API key, signed assertion)PUBLIC›
Initial EMAIL_ENROLLMENT redemption accepts the one-time enrollment credential
returned by POST /agents, but only after an owner has verified email and approved
the requested profile via the trusted hosted link. Redemption is atomic and issues
short-lived access_token, role=AGENT, plus an agent_api_key only once. Never send
these credentials by email. Subsequent authentication uses API_KEY (rotatable,
revocable and rate limited) or SIGNED_ASSERTION with a registered public key.
credential is authentication proof, NEVER a private key. Signed assertions must be
fresh, audience-bound and replay protected. A production sender-constrained access
token (e.g. DPoP/mTLS) is preferable to a reusable bearer token alone.
Retry-After · Seconds or HTTP date until retry · {"type": "string"}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
{
"pathItem": {},
"operation": {
"tags": [
"Authentication"
],
"operationId": "authenticateAgent",
"summary": "Authenticate agent in one call (email enrollment, API key, signed assertion)",
"description": "Initial EMAIL_ENROLLMENT redemption accepts the one-time enrollment credential\nreturned by POST /agents, but only after an owner has verified email and approved\nthe requested profile via the trusted hosted link. Redemption is atomic and issues\nshort-lived access_token, role=AGENT, plus an agent_api_key only once. Never send\nthese credentials by email. Subsequent authentication uses API_KEY (rotatable,\nrevocable and rate limited) or SIGNED_ASSERTION with a registered public key.\ncredential is authentication proof, NEVER a private key. Signed assertions must be\nfresh, audience-bound and replay protected. A production sender-constrained access\ntoken (e.g. DPoP/mTLS) is preferable to a reusable bearer token alone.\n",
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthRequest"
},
"example": {
"agent_id": "agt_8fd231",
"authentication_method": "SIGNED_ASSERTION",
"credential": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImtleS0xIn0..."
}
}
}
},
"responses": {
"200": {
"description": "Short-lived agent access token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
},
"x-agentpay-roles": [
"PUBLIC"
]
}
}
Principals
Individual/business onboarding, trusted representation and agent binding
POST/principalsOnboard an individual or business principalPRINCIPAL / ADMIN / PARTNER›
Principal ID is server generated; it is NOT submitted. Idempotency-Key is a retry
header, not a bearer credential. An authenticated principal session with explicit
onboarding authority or trusted partner/admin channel can create a principal.
principal_type selects either an individual or business profile, never both.
A business must have a verified authorized representative; contact details do
not establish that authority. KYC/KYB verification is a
separate process and spending remains blocked where identity verification is required.
Authentication
HTTP Bearer / JWT
Eligible roles
PRINCIPAL, ADMIN, PARTNER
Individual self-onboarding, verified business-representative authority, or explicitly delegated administrative/partner onboarding.
Parameters
Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409. · {"type": "string", "minLength": 16, "maxLength": 128}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
Use a business profile instead of an individual profile. Declared registration details do not prove representative authority or grant spending permission.
403 Authenticated actor lacks rights to the resource
409 State conflict, optimistic lock or idempotency mismatch
Full OpenAPI operation definition
Full OpenAPI operation definition
{
"pathItem": {},
"operation": {
"tags": [
"Principals"
],
"operationId": "createPrincipal",
"summary": "Onboard an individual or business principal",
"description": "Principal ID is server generated; it is NOT submitted. Idempotency-Key is a retry\nheader, not a bearer credential. An authenticated principal session with explicit\nonboarding authority or trusted partner/admin channel can create a principal.\nprincipal_type selects either an individual or business profile, never both.\nA business must have a verified authorized representative; contact details do\nnot establish that authority. KYC/KYB verification is a\nseparate process and spending remains blocked where identity verification is required.\n",
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePrincipalRequest"
}
}
}
},
"responses": {
"201": {
"description": "Principal profile created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Principal"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
},
"x-agentpay-roles": [
"PRINCIPAL",
"ADMIN",
"PARTNER"
],
"x-agentpay-resource-authorization": "Individual self-onboarding, verified business-representative authority, or explicitly delegated administrative/partner onboarding."
}
}
GET/principals/{principalId}Retrieve principal profilePRINCIPAL / ADMIN / PARTNER›
Only the individual, an authorized representative of the subject business, or an explicitly scoped administrative/partner channel may read sensitive profile fields. A contact email does not establish business authority.
Authentication
HTTP Bearer / JWT
Eligible roles
PRINCIPAL, ADMIN, PARTNER
Self or explicit tenant/portfolio access; no cross-principal read/write.
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
403 Authenticated actor lacks rights to the resource
404 Not found or deliberately hidden from this actor
Full OpenAPI operation definition
Full OpenAPI operation definition
{
"pathItem": {
"parameters": [
{
"$ref": "#/components/parameters/PrincipalId"
}
]
},
"operation": {
"tags": [
"Principals"
],
"operationId": "getPrincipal",
"summary": "Retrieve principal profile",
"description": "Only the individual, an authorized representative of the subject business, or an explicitly scoped administrative/partner channel may read sensitive profile fields. A contact email does not establish business authority.",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Principal profile",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Principal"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-agentpay-roles": [
"PRINCIPAL",
"ADMIN",
"PARTNER"
],
"x-agentpay-resource-authorization": "Self or explicit tenant/portfolio access; no cross-principal read/write."
}
}
PUT/principals/{principalId}Modify principal detailsPRINCIPAL / ADMIN / PARTNER›
Does not accept changes to principal_id, principal_type, verification_status, identity_verification_status, representative authority or externally approved consent. Only the profile matching the stored principal_type can be updated; profile changes may require renewed verification and do not silently update previously verified intents.
Authentication
HTTP Bearer / JWT
Eligible roles
PRINCIPAL, ADMIN, PARTNER
Self or explicit tenant/portfolio access; no cross-principal read/write.
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
403 Authenticated actor lacks rights to the resource
404 Not found or deliberately hidden from this actor
409 State conflict, optimistic lock or idempotency mismatch
401 No valid authentication for this actor
Full OpenAPI operation definition
Full OpenAPI operation definition
{
"pathItem": {
"parameters": [
{
"$ref": "#/components/parameters/PrincipalId"
}
]
},
"operation": {
"tags": [
"Principals"
],
"operationId": "updatePrincipal",
"summary": "Modify principal details",
"description": "Does not accept changes to principal_id, principal_type, verification_status, identity_verification_status, representative authority or externally approved consent. Only the profile matching the stored principal_type can be updated; profile changes may require renewed verification and do not silently update previously verified intents.",
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePrincipalRequest"
}
}
}
},
"responses": {
"200": {
"description": "Updated principal",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Principal"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"x-agentpay-roles": [
"PRINCIPAL",
"ADMIN",
"PARTNER"
],
"x-agentpay-resource-authorization": "Self or explicit tenant/portfolio access; no cross-principal read/write."
}
}
POST/principals/{principalId}/bindBind the authenticated principal to a specified agentPRINCIPAL / ADMIN / PARTNER›
Principal-controlled action performed through a trusted channel. Records
an explicit consent to establish an association with the agent; it does
NOT create carte blanche to spend. The server verifies the authenticated
session is scoped to the requested principal and that the agent is eligible.
For BUSINESS principals, independently verify the authenticated representative's
authority and applicable business spending mandate. An agent cannot approve
its own binding or nominate a business representative as proof of consent.
A stable, opaque agent-scoped principal_reference is returned.
Authentication
HTTP Bearer / JWT
Eligible roles
PRINCIPAL, ADMIN, PARTNER
Principal consent mandatory; admins/partners cannot silently fabricate principal spend approval.
Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409. · {"type": "string", "minLength": 16, "maxLength": 128}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
DELETE/principals/{principalId}/bindings/{agentId}Revoke an agent bindingPRINCIPAL / ADMIN / PARTNER›
Disables future intents and unused capabilities under this binding;
already-authorized transactions may need separate reversal/refund steps.
Audit and transaction records are retained as required.
Authentication
HTTP Bearer / JWT
Eligible roles
PRINCIPAL, ADMIN, PARTNER
Principal consent mandatory; admins/partners cannot silently fabricate principal spend approval.
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
403 Authenticated actor lacks rights to the resource
404 Not found or deliberately hidden from this actor
409 State conflict, optimistic lock or idempotency mismatch
401 No valid authentication for this actor
Full OpenAPI operation definition
Full OpenAPI operation definition
{
"pathItem": {
"parameters": [
{
"$ref": "#/components/parameters/PrincipalId"
},
{
"$ref": "#/components/parameters/AgentId"
}
]
},
"operation": {
"tags": [
"Principals"
],
"operationId": "unbindPrincipalFromAgent",
"summary": "Revoke an agent binding",
"description": "Disables future intents and unused capabilities under this binding;\nalready-authorized transactions may need separate reversal/refund steps.\nAudit and transaction records are retained as required.\n",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"204": {
"description": "Binding revoked"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"x-agentpay-roles": [
"PRINCIPAL",
"ADMIN",
"PARTNER"
],
"x-agentpay-resource-authorization": "Principal consent mandatory; admins/partners cannot silently fabricate principal spend approval."
}
}
Verification
Hosted KYC for individuals and KYB for businesses
POST/principals/{principalId}/verification-sessionCreate a hosted KYC or KYB verification session for a principalPRINCIPAL / ADMIN / PARTNER›
Returns a short-lived hosted verification URL. The authenticated individual or authorized business representative completes verification with a trusted provider, not with the agent. The server selects KYC for INDIVIDUAL or KYB for BUSINESS from the stored principal_type. Business verification includes required representative/ownership checks; a passed KYB result is not a spending mandate. The service accepts verification decisions only from an authenticated provider integration; it must not accept agent-supplied VERIFIED flags. Do not expose PII or submitted identity-document images through these endpoints.
Authentication
HTTP Bearer / JWT
Eligible roles
PRINCIPAL, ADMIN, PARTNER
Subject principal or explicitly authorized onboarding partner.
Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409. · {"type": "string", "minLength": 16, "maxLength": 128}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
Request JSON
{
"locale": "de-AT"
}
201 · Hosted principal verification session created
403 Authenticated actor lacks rights to the resource
404 Not found or deliberately hidden from this actor
409 State conflict, optimistic lock or idempotency mismatch
Full OpenAPI operation definition
Full OpenAPI operation definition
{
"pathItem": {
"parameters": [
{
"$ref": "#/components/parameters/PrincipalId"
}
]
},
"operation": {
"tags": [
"Verification"
],
"operationId": "createPrincipalVerificationSession",
"summary": "Create a hosted KYC or KYB verification session for a principal",
"description": "Returns a short-lived hosted verification URL. The authenticated individual or authorized business representative completes verification with a trusted provider, not with the agent. The server selects KYC for INDIVIDUAL or KYB for BUSINESS from the stored principal_type. Business verification includes required representative/ownership checks; a passed KYB result is not a spending mandate. The service accepts verification decisions only from an authenticated provider integration; it must not accept agent-supplied VERIFIED flags. Do not expose PII or submitted identity-document images through these endpoints.\n",
"security": [
{
"BearerAuth": []
}
],
"x-agentpay-roles": [
"PRINCIPAL",
"ADMIN",
"PARTNER"
],
"x-agentpay-resource-authorization": "Subject principal or explicitly authorized onboarding partner.",
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePrincipalVerificationSessionRequest"
}
}
}
},
"responses": {
"201": {
"description": "Hosted principal verification session created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PrincipalVerificationSession"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
}
}
}
GET/principals/{principalId}/verificationRead principal KYC/KYB status without disclosing underlying identity documentsPRINCIPAL / ADMIN / PARTNER›
Read principal KYC/KYB status without disclosing underlying identity documents
Authentication
HTTP Bearer / JWT
Eligible roles
PRINCIPAL, ADMIN, PARTNER
Subject principal or authorized onboarding/compliance partner.
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
An agent submits its understanding of merchant, basket, prices, billing,
shipping, checkout channel, PSP and principal authorization reference.
Values in this request are agent-declared and must not be treated as
verified merchant/issuer evidence. The agent identity is derived from
the access token. Principal approval cannot be self-asserted by an agent.
The server validates order arithmetic, currency consistency and ownership.
Creating an intent neither approves it nor issues a card/token.
Authentication
HTTP Bearer / JWT
Eligible roles
AGENT, PRINCIPAL, ADMIN, PARTNER
Agent self and bound principal; ADMIN/PARTNER only within authorized scope. Verify cannot replace principal consent.
Parameters
Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409. · {"type": "string", "minLength": 16, "maxLength": 128}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
Request · no JSON body
GET /intents/{intentId}
200 · Intent state and immutable verification evidence references
PUT/intents/{intentId}Replace an unverified draft intentAGENT / PRINCIPAL / ADMIN / PARTNER›
Only allowed for DRAFT or CHANGES_REQUESTED; replaces the mutable
purchase details. Any prior verification result is invalidated. Once
verified, the signed purchase snapshot is immutable: create a new intent
to change material merchant, amount, product, address or checkout fields.
Authentication
HTTP Bearer / JWT
Eligible roles
AGENT, PRINCIPAL, ADMIN, PARTNER
Agent self and bound principal; ADMIN/PARTNER only within authorized scope. Verify cannot replace principal consent.
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
403 Authenticated actor lacks rights to the resource
404 Not found or deliberately hidden from this actor
409 State conflict, optimistic lock or idempotency mismatch
401 No valid authentication for this actor
Full OpenAPI operation definition
Full OpenAPI operation definition
{
"pathItem": {
"parameters": [
{
"$ref": "#/components/parameters/IntentId"
}
]
},
"operation": {
"tags": [
"Intents"
],
"operationId": "updateIntent",
"summary": "Replace an unverified draft intent",
"description": "Only allowed for DRAFT or CHANGES_REQUESTED; replaces the mutable\npurchase details. Any prior verification result is invalidated. Once\nverified, the signed purchase snapshot is immutable: create a new intent\nto change material merchant, amount, product, address or checkout fields.\n",
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateIntentRequest"
}
}
}
},
"responses": {
"200": {
"description": "Updated draft intent",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Intent"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"x-agentpay-roles": [
"AGENT",
"PRINCIPAL",
"ADMIN",
"PARTNER"
],
"x-agentpay-resource-authorization": "Agent self and bound principal; ADMIN/PARTNER only within authorized scope. Verify cannot replace principal consent."
}
}
POST/intents/{intentId}/verifyVerify checkout intent against delegation, trusted consent, evidence and policyAGENT / PRINCIPAL / ADMIN / PARTNER›
Separate explicit step from payment credential issuance. Looks up
principal-agent binding and actual consent/mandate in a trusted system;
a client-supplied consent reference is never independent proof. Performs
deterministic hard-rule checks (agent, principal, amount, currency,
merchant allowlist, goods/geography, validity, frequency and prior use).
Probabilistic risk or AI-based signals may only inform a manual review or
step-up decision, not override hard restrictions. If principal approval
is missing, returns STEP_UP_REQUIRED with a secure principal action URL.
VERIFIED is only set once all required consent and verification succeed.
Product, address, and PSP claims can be assessed before checkout using
independent evidence where available; they are not assumed observable
during standard issuer authorization.
Where identity verification is required, an unverified principal cannot receive
spend authority; return STEP_UP_REQUIRED with a KYC/KYB verification action, or domain error
identity_verification_required as appropriate. Agent KYA and principal/agent limits
are independently enforced and untrusted agent profile mismatches inform risk.
Authentication
HTTP Bearer / JWT
Eligible roles
AGENT, PRINCIPAL, ADMIN, PARTNER
Agent self and bound principal; ADMIN/PARTNER only within authorized scope. Verify cannot replace principal consent.
Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409. · {"type": "string", "minLength": 16, "maxLength": 128}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
Request JSON
{
"note": "Principal approval is available for review"
}
200 · Verification decision (including decline or principal step-up)
403 Authenticated actor lacks rights to the resource
404 Not found or deliberately hidden from this actor
409 State conflict, optimistic lock or idempotency mismatch
503 Dependency unavailable; no implicit authorization or approval
401 No valid authentication for this actor
Full OpenAPI operation definition
Full OpenAPI operation definition
{
"pathItem": {
"parameters": [
{
"$ref": "#/components/parameters/IntentId"
}
]
},
"operation": {
"tags": [
"Intents"
],
"operationId": "verifyIntent",
"summary": "Verify checkout intent against delegation, trusted consent, evidence and policy",
"description": "Separate explicit step from payment credential issuance. Looks up\nprincipal-agent binding and actual consent/mandate in a trusted system;\na client-supplied consent reference is never independent proof. Performs\ndeterministic hard-rule checks (agent, principal, amount, currency,\nmerchant allowlist, goods/geography, validity, frequency and prior use).\nProbabilistic risk or AI-based signals may only inform a manual review or\nstep-up decision, not override hard restrictions. If principal approval\nis missing, returns STEP_UP_REQUIRED with a secure principal action URL.\nVERIFIED is only set once all required consent and verification succeed.\nProduct, address, and PSP claims can be assessed before checkout using\nindependent evidence where available; they are not assumed observable\nduring standard issuer authorization.\nWhere identity verification is required, an unverified principal cannot receive\nspend authority; return STEP_UP_REQUIRED with a KYC/KYB verification action, or domain error\nidentity_verification_required as appropriate. Agent KYA and principal/agent limits\nare independently enforced and untrusted agent profile mismatches inform risk.\n",
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyIntentRequest"
}
}
}
},
"responses": {
"200": {
"description": "Verification decision (including decline or principal step-up)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntentVerification"
},
"examples": {
"verified": {
"value": {
"verification_id": "vrf_123",
"intent_id": "int_123",
"decision": "APPROVED",
"intent_status": "VERIFIED",
"policy_version": "0.3.0",
"reason_codes": [
"AGENT_ACTIVE",
"BINDING_ACTIVE",
"PRINCIPAL_AUTHORIZED",
"AMOUNT_WITHIN_LIMIT"
],
"verified_snapshot_hash": "sha256:0123456789abcdef",
"evidence_id": "ev_123",
"verified_at": "2026-10-08T14:00:00Z"
}
},
"needsStepUp": {
"value": {
"verification_id": "vrf_124",
"intent_id": "int_123",
"decision": "STEP_UP_REQUIRED",
"intent_status": "STEP_UP_REQUIRED",
"policy_version": "0.3.0",
"reason_codes": [
"PRINCIPAL_APPROVAL_REQUIRED"
],
"principal_action": {
"authorization_url": "https://consent.agentpay.example/approve/opaque",
"expires_at": "2026-10-08T14:05:00Z"
},
"evidence_id": "ev_124"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"503": {
"$ref": "#/components/responses/Unavailable"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"x-agentpay-roles": [
"AGENT",
"PRINCIPAL",
"ADMIN",
"PARTNER"
],
"x-agentpay-resource-authorization": "Agent self and bound principal; ADMIN/PARTNER only within authorized scope. Verify cannot replace principal consent."
}
}
Payments
Payment capability issuance, status and reversal requests
POST/intents/{intentId}/payRequest a one-use payment method for a verified intentAGENT / PRINCIPAL / ADMIN / PARTNER›
Creates one payment attempt for a previously VERIFIED purchase intent.
No client TTL parameter. Server sets nominal 60-second one-use capability window.
For VIRTUAL_CARD (existing EPHEMERAL_CARD rail) issuer processor issues one unique
card identifier per attempt; Agent Pay stores immutable credential_id -> payment_id
-> intent_id and issuer processor_card_id mappings. Agent may receive a ONE-TIME
sensitive card object (PAN, CVV, expiry, sponsor-approved alphabetic cardholder name)
in this POST response if issuance and PCI delivery permit it. All GET endpoints and
idempotent replays provide redacted card metadata ONLY. Never log/store CVV after
authorization. Network agentic rails can return a separate restricted token handoff;
equivalent issuer-token-to-intent binding must be confirmed. Checkout/merchant charges
happen outside this API; successful credential issuance does not imply authorization.
One intent may have failed/expired payment attempts, but only one distinct successful
purchase; issuer auth retries and lifecycle events are deduplicated atomically.
Authentication
HTTP Bearer / JWT
Eligible roles
AGENT, PRINCIPAL, ADMIN, PARTNER
Only authorized agent or specifically delegated permitted actor; principal approval and verified intent remain mandatory.
Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409. · {"type": "string", "minLength": 16, "maxLength": 128}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
Request JSON
{
"requested_rail": "AUTO"
}
201 · One-time issued payment payload; sensitive card fields ONLY on first eligible response
403 Authenticated actor lacks rights to the resource
404 Not found or deliberately hidden from this actor
409 State conflict, optimistic lock or idempotency mismatch
422 Includes identity_verification_required when principal KYC/KYB is incomplete · identity_verification_required
503 Dependency unavailable; no implicit authorization or approval
401 No valid authentication for this actor
Card secrets, if issuance permits them, appear only in the initial issuance response. GET endpoints and idempotent replays remain redacted. The nominal 60-second initiation window is system controlled. Issuance does not confirm a purchase; outcome requires trusted processor events.
Full OpenAPI operation definition
Full OpenAPI operation definition
{
"pathItem": {
"parameters": [
{
"$ref": "#/components/parameters/IntentId"
}
]
},
"operation": {
"tags": [
"Payments"
],
"operationId": "requestPaymentCapability",
"summary": "Request a one-use payment method for a verified intent",
"description": "Creates one payment attempt for a previously VERIFIED purchase intent.\nNo client TTL parameter. Server sets nominal 60-second one-use capability window.\nFor VIRTUAL_CARD (existing EPHEMERAL_CARD rail) issuer processor issues one unique\ncard identifier per attempt; Agent Pay stores immutable credential_id -> payment_id\n-> intent_id and issuer processor_card_id mappings. Agent may receive a ONE-TIME\nsensitive card object (PAN, CVV, expiry, sponsor-approved alphabetic cardholder name)\nin this POST response if issuance and PCI delivery permit it. All GET endpoints and\nidempotent replays provide redacted card metadata ONLY. Never log/store CVV after\nauthorization. Network agentic rails can return a separate restricted token handoff;\nequivalent issuer-token-to-intent binding must be confirmed. Checkout/merchant charges\nhappen outside this API; successful credential issuance does not imply authorization.\nOne intent may have failed/expired payment attempts, but only one distinct successful\npurchase; issuer auth retries and lifecycle events are deduplicated atomically.\n",
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RequestPaymentCapability"
},
"example": {
"requested_rail": "AUTO"
}
}
}
},
"responses": {
"201": {
"description": "One-time issued payment payload; sensitive card fields ONLY on first eligible response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentIssuanceResponse"
},
"example": {
"payment": {
"payment_id": "pay_456",
"intent_id": "int_123",
"status": "CREDENTIAL_ISSUED",
"decision": "APPROVED",
"rail": "EPHEMERAL_CARD",
"amount": {
"value": "49.99",
"currency": "EUR"
},
"correlation_id": "corr_123",
"capability_id": "cap_123",
"capability_expires_at": "2026-10-08T17:31:00Z",
"card": {
"credential_id": "cred_789",
"last4": "1111",
"gateway_token": {
"provider": "example_psp",
"token_id": "gtw_abc123"
}
},
"created_at": "2026-10-08T17:30:00Z",
"updated_at": "2026-10-08T17:30:00Z"
},
"card": {
"credential_id": "cred_789",
"pan": "4111111111111111",
"cvv": "123",
"expiry_month": "10",
"expiry_year": "2027",
"cardholder_name": "AGENTPAY RIVER",
"last4": "1111",
"gateway_token": {
"provider": "example_psp",
"token_id": "gtw_abc123"
}
}
}
}
},
"headers": {
"Cache-Control": {
"description": "Sensitive responses must have no-store",
"schema": {
"type": "string"
},
"example": "no-store"
}
}
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"description": "Includes identity_verification_required when principal KYC/KYB is incomplete",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"code": "identity_verification_required",
"message": "Principal must complete hosted identity verification before spending.",
"correlation_id": "corr_123",
"retryable": false
}
}
}
},
"503": {
"$ref": "#/components/responses/Unavailable"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"x-agentpay-roles": [
"AGENT",
"PRINCIPAL",
"ADMIN",
"PARTNER"
],
"x-agentpay-resource-authorization": "Only authorized agent or specifically delegated permitted actor; principal approval and verified intent remain mandatory."
}
}
GET/intents/{intentId}/payList payment IDs, rails, statuses and timestamps (no card secrets)AGENT / PRINCIPAL / ADMIN / PARTNER›
List payment IDs, rails, statuses and timestamps (no card secrets)
Authentication
HTTP Bearer / JWT
Eligible roles
AGENT, PRINCIPAL, ADMIN, PARTNER
Bound agent, principal or authorized portfolio. Never reveal another principal’s payment details.
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
403 Authenticated actor lacks rights to the resource
404 Not found or deliberately hidden from this actor
401 No valid authentication for this actor
Card secrets, if issuance permits them, appear only in the initial issuance response. GET endpoints and idempotent replays remain redacted. The nominal 60-second initiation window is system controlled. Issuance does not confirm a purchase; outcome requires trusted processor events.
GET/intents/{intentId}/pay/{paymentId}Get complete payment record with only token ID and PAN last4AGENT / PRINCIPAL / ADMIN / PARTNER›
Returns authorized payment metadata, rail, processor-confirmed status,
issuer authorization references, safe card details (credential_id, last4 and
scope-authorized PSP gateway token ID), but NEVER PAN, CVV or expiration date.
The PSP token is not the canonical issuer correlation ID and may still be sensitive.
Captured/settled status requires trusted processor events, not agent declaration.
Authentication
HTTP Bearer / JWT
Eligible roles
AGENT, PRINCIPAL, ADMIN, PARTNER
Bound agent, principal or authorized portfolio. Never reveal another principal’s payment details.
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
403 Authenticated actor lacks rights to the resource
404 Not found or deliberately hidden from this actor
401 No valid authentication for this actor
Card secrets, if issuance permits them, appear only in the initial issuance response. GET endpoints and idempotent replays remain redacted. The nominal 60-second initiation window is system controlled. Issuance does not confirm a purchase; outcome requires trusted processor events.
Full OpenAPI operation definition
Full OpenAPI operation definition
{
"pathItem": {
"parameters": [
{
"$ref": "#/components/parameters/IntentId"
},
{
"$ref": "#/components/parameters/PaymentId"
}
]
},
"operation": {
"tags": [
"Payments"
],
"operationId": "getIntentPayment",
"summary": "Get complete payment record with only token ID and PAN last4",
"description": "Returns authorized payment metadata, rail, processor-confirmed status,\nissuer authorization references, safe card details (credential_id, last4 and\nscope-authorized PSP gateway token ID), but NEVER PAN, CVV or expiration date.\nThe PSP token is not the canonical issuer correlation ID and may still be sensitive.\nCaptured/settled status requires trusted processor events, not agent declaration.\n",
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Payment attempt",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Payment"
}
}
}
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"x-agentpay-roles": [
"AGENT",
"PRINCIPAL",
"ADMIN",
"PARTNER"
],
"x-agentpay-resource-authorization": "Bound agent, principal or authorized portfolio. Never reveal another principal’s payment details."
}
}
POST/intents/{intentId}/pay/{paymentId}/reverseRequest capability cancellation, authorization reversal or merchant refundAGENT / PRINCIPAL / ADMIN / PARTNER›
An unused capability can be cancelled. Reversing an authorization depends
on sponsor/issuer/processor support. A captured/settled transaction may
require a separate merchant refund, not a card authorization reversal;
REFUND_REQUEST is only offered where a permitted integration exists.
A success here means a reversal operation was accepted, not that funds
were returned. Use the returned status and check actual rail events.
API retains /reverse as explicitly requested.
Authentication
HTTP Bearer / JWT
Eligible roles
AGENT, PRINCIPAL, ADMIN, PARTNER
Bound agent, principal or authorized portfolio. Never reveal another principal’s payment details.
Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409. · {"type": "string", "minLength": 16, "maxLength": 128}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
403 Authenticated actor lacks rights to the resource
404 Not found or deliberately hidden from this actor
409 State conflict, optimistic lock or idempotency mismatch
422 Well-formed request fails domain or financial validation
401 No valid authentication for this actor
Card secrets, if issuance permits them, appear only in the initial issuance response. GET endpoints and idempotent replays remain redacted. The nominal 60-second initiation window is system controlled. Issuance does not confirm a purchase; outcome requires trusted processor events.
Full OpenAPI operation definition
Full OpenAPI operation definition
{
"pathItem": {
"parameters": [
{
"$ref": "#/components/parameters/IntentId"
},
{
"$ref": "#/components/parameters/PaymentId"
}
]
},
"operation": {
"tags": [
"Payments"
],
"operationId": "reverseIntentPayment",
"summary": "Request capability cancellation, authorization reversal or merchant refund",
"description": "An unused capability can be cancelled. Reversing an authorization depends\non sponsor/issuer/processor support. A captured/settled transaction may\nrequire a separate merchant refund, not a card authorization reversal;\nREFUND_REQUEST is only offered where a permitted integration exists.\nA success here means a reversal operation was accepted, not that funds\nwere returned. Use the returned status and check actual rail events.\nAPI retains /reverse as explicitly requested.\n",
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReversePaymentRequest"
}
}
}
},
"responses": {
"202": {
"description": "Reversal request received for asynchronous processing",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReversalOperation"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"x-agentpay-roles": [
"AGENT",
"PRINCIPAL",
"ADMIN",
"PARTNER"
],
"x-agentpay-resource-authorization": "Bound agent, principal or authorized portfolio. Never reveal another principal’s payment details."
}
}
Issuer Integration
Internal issuer/processor-facing, NOT exposed to untrusted agents
POST/issuer/authorizations/evaluateCompare an issuer-reported card authorization with a verified intentPARTNER · mTLS›
Trusted issuer/processor callback. Resolve processor_card_id or agreed
credential_reference to one internally issued credential -> payment -> intent.
Never use CVV, expiry, cardholder name or gateway token as issuer matching key.
Atomically reserve/consume one successful purchase per intent, distinguishing
retries/reversals and partial authorizations. Compare actual amount, currency,
merchant/MID/MCC/country as available, verified snapshot and system expiry.
Shipping, product SKUs, billing address and PSP URL are typically unavailable
in an authorization; evidence must be sourced separately, with provenance.
No agent API token can call this endpoint. Fail-closed/timeout policy is issuer-agreed.
Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409. · {"type": "string", "minLength": 16, "maxLength": 128}
YAML examples are reproduced as supplied; dates and credential values are illustrative. Where the YAML has no example, a schema-valid example is generated. Examples do not list every optional field; follow the schema links for complete definitions.
{"type": "string", "description": "ONLY returned once at successful first EMAIL_ENROLLMENT; store securely, revocable/rotatable; never returned by GET APIs", "x-sensitive": true}
ONLY returned once at successful first EMAIL_ENROLLMENT; store securely, revocable/rotatable; never returned by GET APIs
Full JSON Schema definition
Full JSON Schema definition
{
"type": "object",
"additionalProperties": false,
"required": [
"access_token",
"token_type",
"expires_in",
"agent_id",
"role"
],
"properties": {
"access_token": {
"type": "string",
"description": "Short-lived bearer access token; never log"
},
"token_type": {
"type": "string",
"const": "Bearer"
},
"expires_in": {
"type": "integer",
"minimum": 1,
"example": 3600
},
"agent_id": {
"type": "string"
},
"role": {
"type": "string",
"const": "AGENT"
},
"scope": {
"type": "string"
},
"agent_api_key": {
"type": "string",
"description": "ONLY returned once at successful first EMAIL_ENROLLMENT; store securely, revocable/rotatable; never returned by GET APIs",
"x-sensitive": true
}
}
}
Address
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
Declared business identity, not proof of verification or representative authority. Required evidence is resolved by the trusted KYB provider and policy.
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
BusinessPrincipalProfile fields
Field
Presence
Definition
legal_name
required
{"type": "string", "minLength": 1}
trading_name
optional
{"type": "string", "minLength": 1}
registration_country
required
{"type": "string", "pattern": "^[A-Z]{2}$"}
registration_number
optional
{"type": "string", "minLength": 1}
Full JSON Schema definition
Full JSON Schema definition
{
"type": "object",
"additionalProperties": false,
"required": [
"legal_name",
"registration_country"
],
"description": "Declared business identity, not proof of verification or representative authority. Required evidence is resolved by the trusted KYB provider and policy.",
"properties": {
"legal_name": {
"type": "string",
"minLength": 1
},
"trading_name": {
"type": "string",
"minLength": 1
},
"registration_country": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"registration_number": {
"type": "string",
"minLength": 1
}
}
}
CreatePrincipalRequest
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
Only the nested profile matching the existing principal_type may be supplied. That match is enforced against the stored principal server-side; principal_type and trusted verification/authority fields are immutable through this request.
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
{"type": "string", "enum": ["PENDING", "VERIFIED", "RESTRICTED"], "description": "Trusted principal onboarding status; never supplied by an agent or self-declared representative. Identity verification and spending authority remain separate checks."}
Trusted principal onboarding status; never supplied by an agent or self-declared representative. Identity verification and spending authority remain separate checks.
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
BindPrincipalRequest fields
Field
Presence
Definition
agent_id
required
{"type": "string", "example": "agt_123"}
consent_acknowledged
required
{"type": "boolean", "const": true, "description": "UX acknowledgment; not standalone proof. The trusted principal session and consent record are verified server-side."}
UX acknowledgment; not standalone proof. The trusted principal session and consent record are verified server-side.
requested_binding_label
optional
{"type": "string", "description": "Friendly label visible to principal"}
Friendly label visible to principal
Full JSON Schema definition
Full JSON Schema definition
{
"type": "object",
"additionalProperties": false,
"required": [
"agent_id",
"consent_acknowledged"
],
"properties": {
"agent_id": {
"type": "string",
"example": "agt_123"
},
"consent_acknowledged": {
"type": "boolean",
"const": true,
"description": "UX acknowledgment; not standalone proof. The trusted principal session and consent record are verified server-side."
},
"requested_binding_label": {
"type": "string",
"description": "Friendly label visible to principal"
}
}
}
PrincipalBinding
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
Reference to trusted principal authorization. References supplied by agents must be resolved server-side; self-asserted approvals are not valid.
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
AuthorizationReference fields
Field
Presence
Definition
mandate_reference
optional
{"type": "string", "description": "Existing bank or AP2-style mandate, if supported"}
Existing bank or AP2-style mandate, if supported
consent_reference
optional
{"type": "string", "description": "Agent Pay-approved specific principal consent, if available"}
Agent Pay-approved specific principal consent, if available
principal_approval_context
optional
{"type": "string", "description": "Non-authoritative human-readable explanation shown to principal"}
Non-authoritative human-readable explanation shown to principal
Full JSON Schema definition
Full JSON Schema definition
{
"type": "object",
"additionalProperties": false,
"description": "Reference to trusted principal authorization. References supplied by agents must be resolved server-side; self-asserted approvals are not valid.",
"properties": {
"mandate_reference": {
"type": "string",
"description": "Existing bank or AP2-style mandate, if supported"
},
"consent_reference": {
"type": "string",
"description": "Agent Pay-approved specific principal consent, if available"
},
"principal_approval_context": {
"type": "string",
"description": "Non-authoritative human-readable explanation shown to principal"
}
}
}
EvidenceReference
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
{"type": "object", "description": "Non-authoritative agent-provided metadata; never used directly as an authorization rule.", "additionalProperties": {"type": "string"}}
Non-authoritative agent-provided metadata; never used directly as an authorization rule.
{
"type": "object",
"additionalProperties": false,
"description": "Optional request to rerun verification after principal approval or supporting evidence has changed.",
"properties": {
"evidence_references": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EvidenceReference"
}
},
"note": {
"type": "string",
"maxLength": 500
}
}
}
PrincipalAction
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
PrincipalAction fields
Field
Presence
Definition
authorization_url
required
{"type": "string", "format": "uri", "description": "Hosted HTTPS principal/bank approval page for the individual or authorized business representative; agent may display but cannot approve"}
Hosted HTTPS principal/bank approval page for the individual or authorized business representative; agent may display but cannot approve
expires_at
required
{"type": "string", "format": "date-time"}
Full JSON Schema definition
Full JSON Schema definition
{
"type": "object",
"additionalProperties": false,
"required": [
"authorization_url",
"expires_at"
],
"properties": {
"authorization_url": {
"type": "string",
"format": "uri",
"description": "Hosted HTTPS principal/bank approval page for the individual or authorized business representative; agent may display but cannot approve"
},
"expires_at": {
"type": "string",
"format": "date-time"
}
}
}
IntentVerification
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
Card metadata is redacted. Only token_id (if scope permits) and PAN last4 may be exposed. No PAN, CVV, expiry or cardholder name on GET. One-use virtual card credentials are emitted only on initial POST /pay. Issuer outcomes must be processor-confirmed.
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
The issuer sends its actually available authorization data only;
do not invent billing/shipping or product fields. Merchant MID and descriptor
matching may need acquirer mappings. Missing mandatory context follows
bank-agreed fail-closed rules.
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
IssuerAuthorizationEvent fields
Field
Presence
Definition
issuer_event_id
required
{"type": "string", "description": "Unique issuer/processor event for deduplication"}
Unique issuer/processor event for deduplication
processor_card_id
conditional
{"type": "string", "description": "Issuer-processor internal card ID; preferred stable one-attempt-to-one-intent lookup for disposable cards; never a PAN"}
Issuer-processor internal card ID; preferred stable one-attempt-to-one-intent lookup for disposable cards; never a PAN
credential_reference
conditional
{"type": "string", "description": "Fallback opaque issuer network-token or card reference when processor_card_id is not supplied; NOT gateway token ID"}
Fallback opaque issuer network-token or card reference when processor_card_id is not supplied; NOT gateway token ID
{"type": "object", "additionalProperties": false, "description": "Issuer-observed 3DS result signals, where available; no assumption of addresses or cart data.", "properties": {"eci": {"type": "string"}, "authentication_status": {"type": "string"}, "ds_transaction_id": {"type": "string"}}}
Issuer-observed 3DS result signals, where available; no assumption of addresses or cart data.
optional_enrichment
optional
{"type": "object", "description": "Out-of-band evidence only. The engine must verify the provider, origin and signature before using it as a trusted match signal.", "additionalProperties": false, "properties": {"provenance": {"type": "string", "enum": ["MERCHANT_SIGNED", "PSP_SIGNED", "UNKNOWN"]}, "evidence_reference": {"type": "string"}}}
Out-of-band evidence only. The engine must verify the provider, origin and signature before using it as a trusted match signal.
occurred_at
required
{"type": "string", "format": "date-time"}
authorization_type
optional
{"type": "string", "enum": ["INITIAL", "RETRY", "INCREMENTAL", "REVERSAL_ADVICE"], "description": "Distinguishes a repeat network event from a second purchase; issuer-specific lifecycle mapping required"}
Distinguishes a repeat network event from a second purchase; issuer-specific lifecycle mapping required
original_authorization_reference
optional
{"type": "string", "description": "Stable prior authorization reference, when applicable"}
Stable prior authorization reference, when applicable
Full JSON Schema definition
Full JSON Schema definition
{
"type": "object",
"additionalProperties": false,
"required": [
"issuer_event_id",
"amount",
"merchant",
"occurred_at"
],
"description": "The issuer sends its actually available authorization data only;\ndo not invent billing/shipping or product fields. Merchant MID and descriptor\nmatching may need acquirer mappings. Missing mandatory context follows\nbank-agreed fail-closed rules.\n",
"properties": {
"issuer_event_id": {
"type": "string",
"description": "Unique issuer/processor event for deduplication"
},
"processor_card_id": {
"type": "string",
"description": "Issuer-processor internal card ID; preferred stable one-attempt-to-one-intent lookup for disposable cards; never a PAN"
},
"credential_reference": {
"type": "string",
"description": "Fallback opaque issuer network-token or card reference when processor_card_id is not supplied; NOT gateway token ID"
},
"amount": {
"$ref": "#/components/schemas/Money"
},
"merchant": {
"type": "object",
"additionalProperties": false,
"required": [
"descriptor"
],
"properties": {
"descriptor": {
"type": "string"
},
"merchant_id": {
"type": "string"
},
"acquirer_id": {
"type": "string"
},
"mcc": {
"type": "string",
"pattern": "^[0-9]{4}$"
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"terminal_id": {
"type": "string"
}
}
},
"card_auth_reference": {
"type": "string"
},
"network_transaction_id": {
"type": "string"
},
"network_agentic_indicator": {
"type": "boolean"
},
"three_ds": {
"type": "object",
"additionalProperties": false,
"description": "Issuer-observed 3DS result signals, where available; no assumption of addresses or cart data.",
"properties": {
"eci": {
"type": "string"
},
"authentication_status": {
"type": "string"
},
"ds_transaction_id": {
"type": "string"
}
}
},
"optional_enrichment": {
"type": "object",
"description": "Out-of-band evidence only. The engine must verify the provider, origin and signature before using it as a trusted match signal.",
"additionalProperties": false,
"properties": {
"provenance": {
"type": "string",
"enum": [
"MERCHANT_SIGNED",
"PSP_SIGNED",
"UNKNOWN"
]
},
"evidence_reference": {
"type": "string"
}
}
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"authorization_type": {
"type": "string",
"enum": [
"INITIAL",
"RETRY",
"INCREMENTAL",
"REVERSAL_ADVICE"
],
"description": "Distinguishes a repeat network event from a second purchase; issuer-specific lifecycle mapping required"
},
"original_authorization_reference": {
"type": "string",
"description": "Stable prior authorization reference, when applicable"
}
},
"anyOf": [
{
"required": [
"processor_card_id"
]
},
{
"required": [
"credential_reference"
]
}
]
}
IssuerAuthorizationDecision
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
{"type": "string", "description": "Single-use secret retained by the registering runtime, redeemable ONLY after verified email approval; never sent in email", "x-sensitive": true}
Single-use secret retained by the registering runtime, redeemable ONLY after verified email approval; never sent in email
Server-selected KYC for an INDIVIDUAL or KYB for a BUSINESS; verification does not establish spending authority.
Full JSON Schema definition
Full JSON Schema definition
{
"type": "string",
"enum": [
"KYC",
"KYB"
],
"readOnly": true,
"description": "Server-selected KYC for an INDIVIDUAL or KYB for a BUSINESS; verification does not establish spending authority."
}
CreatePrincipalVerificationSessionRequest
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
CreatePrincipalVerificationSessionRequest fields
Field
Presence
Definition
return_url
optional
{"type": "string", "format": "uri", "description": "Optional allowlisted front-end return URL, never an arbitrary redirect target"}
Optional allowlisted front-end return URL, never an arbitrary redirect target
{"type": "string", "format": "uri", "description": "Hosted provider/Agent Pay verification link for the individual or authorized business representative, never completed by the agent"}
Hosted provider/Agent Pay verification link for the individual or authorized business representative, never completed by the agent
expires_at
required
{"type": "string", "format": "date-time"}
Full JSON Schema definition
Full JSON Schema definition
{
"type": "object",
"additionalProperties": false,
"required": [
"verification_id",
"principal_id",
"verification_type",
"status",
"verification_url",
"expires_at"
],
"properties": {
"verification_id": {
"type": "string",
"example": "ver_123456"
},
"principal_id": {
"type": "string"
},
"verification_type": {
"$ref": "#/components/schemas/PrincipalVerificationType"
},
"status": {
"$ref": "#/components/schemas/PrincipalVerificationStatus"
},
"verification_url": {
"type": "string",
"format": "uri",
"description": "Hosted provider/Agent Pay verification link for the individual or authorized business representative, never completed by the agent"
},
"expires_at": {
"type": "string",
"format": "date-time"
}
}
}
PrincipalVerification
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
HIGHLY SENSITIVE: returned at most once on authorized initial POST /pay over controlled PCI-compliant delivery. Never exposed by GET, logs, analytics or replay. CVV must not be stored post authorization. This schema increases PCI scope.
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
OneTimeVirtualCard fields
Field
Presence
Definition
credential_id
required
{"type": "string"}
pan
required
{"type": "string", "pattern": "^[0-9]{12,19}$", "description": "Card number for one-use checkout; sample data only in docs", "x-sensitive": true}
Card number for one-use checkout; sample data only in docs
cvv
required
{"type": "string", "pattern": "^[0-9]{3,4}$", "description": "Transient card security value; never log or store after authorization", "x-sensitive": true}
Transient card security value; never log or store after authorization
{
"type": "object",
"additionalProperties": false,
"required": [
"credential_id",
"pan",
"cvv",
"expiry_month",
"expiry_year",
"cardholder_name",
"last4"
],
"description": "HIGHLY SENSITIVE: returned at most once on authorized initial POST /pay over controlled PCI-compliant delivery. Never exposed by GET, logs, analytics or replay. CVV must not be stored post authorization. This schema increases PCI scope.\n",
"properties": {
"credential_id": {
"type": "string"
},
"pan": {
"type": "string",
"pattern": "^[0-9]{12,19}$",
"description": "Card number for one-use checkout; sample data only in docs",
"x-sensitive": true
},
"cvv": {
"type": "string",
"pattern": "^[0-9]{3,4}$",
"description": "Transient card security value; never log or store after authorization",
"x-sensitive": true
},
"expiry_month": {
"type": "string",
"pattern": "^(0[1-9]|1[0-2])$"
},
"expiry_year": {
"type": "string",
"pattern": "^[0-9]{4}$"
},
"cardholder_name": {
"type": "string",
"pattern": "^[A-Z ]+$",
"example": "AGENTPAY RIVER",
"description": "Sponsor-approved alphabetic dictionary value; not used for transaction binding"
},
"last4": {
"type": "string",
"pattern": "^[0-9]{4}$"
},
"gateway_token": {
"$ref": "#/components/schemas/GatewayToken"
}
}
}
PaymentIssuanceResponse
Payment record and optional ONE-TIME card payload for virtual-card rail. When creating a network-native agentic token, network_capability may be returned instead of card. No full credentials on repeat requests or GET responses.
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
{
"type": "object",
"additionalProperties": false,
"required": [
"payment"
],
"description": "Payment record and optional ONE-TIME card payload for virtual-card rail. When creating a network-native agentic token, network_capability may be returned instead of card. No full credentials on repeat requests or GET responses.\n",
"properties": {
"payment": {
"$ref": "#/components/schemas/Payment"
},
"card": {
"$ref": "#/components/schemas/OneTimeVirtualCard"
},
"network_capability": {
"$ref": "#/components/schemas/CheckoutHandoff"
}
}
}
PaymentSummary
Required fields are unconditional. Conditional fields depend on a schema branch; full conditions and nested constraints are in the definition below.
