{"openapi":"3.1.0","info":{"title":"PAYAI Agent Commerce API","version":"1.3.0","description":"Provider-neutral Selection Link, Review & Pay, Authorized Agent Pay, quote, payment, and status interfaces. Quotes are authoritative snapshots; agents must not calculate final totals or invent buyer data."},"servers":[{"url":"https://localhost:3000"}],"tags":[{"name":"Discovery"},{"name":"Quotes"},{"name":"Authorizations"},{"name":"Orders"},{"name":"Payments"},{"name":"Tracking"}],"paths":{"/api/agent/v1/storefronts/{slug}/manifest":{"get":{"tags":["Discovery"],"operationId":"getStorefrontManifest","summary":"Discover one storefront and its agent-commerce endpoints","parameters":[{"$ref":"#/components/parameters/StorefrontSlug"}],"responses":{"200":{"description":"Storefront-specific discovery document with all three checkout paths","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontManifest"}}}},"404":{"description":"Storefront not found"}}}},"/api/agent/v1/storefronts/{slug}/payment-capabilities":{"get":{"tags":["Discovery"],"operationId":"getPaymentCapabilities","summary":"List only entitled, connected, provider-ready payment rails","parameters":[{"$ref":"#/components/parameters/StorefrontSlug"}],"responses":{"200":{"description":"Current storefront payment capabilities. Autonomous-looking rails remain conditional until identity, mandate, credential, provider, and policy checks pass; a quote is still authoritative."}}}},"/api/agent/v1/storefronts/{slug}/quotes":{"post":{"tags":["Quotes"],"operationId":"createQuote","summary":"Create an immutable, expiring quote","parameters":[{"$ref":"#/components/parameters/StorefrontSlug"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"201":{"description":"Quote created","content":{"application/json":{"schema":{"type":"object","required":["quote"],"properties":{"quote":{"$ref":"#/components/schemas/Quote"}}}}}},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/agent/v1/quotes/{id}/authorizations":{"post":{"tags":["Authorizations"],"operationId":"authorizeQuote","summary":"Verify a signed PAYAI JWS buyer mandate","description":"Generic AP2 payloads are not accepted without a configured AP2 profile and verifier. Unsupported AP2 requests return a safe Review & Pay order-creation fallback.","security":[{"agentBearer":[],"dpop":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mandate"],"properties":{"mandate":{"type":"string","minLength":64,"maxLength":16384,"description":"Compact signed mandate. PAYAI stores only its safe proof hash."}},"additionalProperties":false}}}},"responses":{"201":{"description":"Mandate verified and bound to this agent and quote"},"401":{"description":"Agent token, DPoP proof, or mandate signature invalid"},"403":{"description":"Mandate is outside the quote scope"},"422":{"description":"Mandate format unsupported or invalid. AP2_MANDATE_UNSUPPORTED includes error.details.fallback with the Review & Pay order endpoint."}}}},"/api/agent/v1/quotes/{id}/orders":{"post":{"tags":["Orders"],"operationId":"createOrder","summary":"Create one order from a valid quote","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"}}}},"responses":{"201":{"description":"Order created. Store the returned capability token securely.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderActionResponse"}}}},"409":{"$ref":"#/components/responses/Conflict"}}}},"/api/agent/v1/orders/{id}/payment":{"get":{"tags":["Payments"],"operationId":"getPaymentRequirement","summary":"Local/test compatibility x402 challenge","deprecated":true,"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"Order was already paid"},"402":{"description":"Payment required","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 V2 PaymentRequired object","schema":{"type":"string"}}}}}},"post":{"tags":["Payments"],"operationId":"submitX402Payment","summary":"Local/test compatibility x402 submission","deprecated":true,"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"name":"PAYMENT-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Base64-encoded x402 V2 PaymentPayload"}],"responses":{"200":{"description":"Settled; PAYMENT-RESPONSE contains the settlement response"},"402":{"description":"Payment is still required"},"403":{"description":"Local simulator is unavailable on deployed hosts"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/api/agent/v1/orders/{id}/payment/simulate":{"post":{"tags":["Payments"],"operationId":"simulatePayment","summary":"Local/test-only settlement simulation; never a live capability","deprecated":true,"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["proof"],"properties":{"proof":{"type":"string","minLength":8}},"additionalProperties":false}}}},"responses":{"200":{"description":"Simulated settlement completed"},"403":{"description":"Simulation is blocked for production and live networks"}}}},"/api/pay/{token}/attempts":{"post":{"tags":["Payments"],"operationId":"createHumanPaymentAttempt","summary":"Create a provider session after the customer selects a Review & Pay method","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","minLength":32}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider"],"properties":{"provider":{"enum":["STRIPE","MOLLIE","PAYPAL","MANUAL_BANK","X402"]}},"additionalProperties":false}}}},"responses":{"201":{"description":"Provider-pinned checkout instruction created; this is not proof of payment"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/api/agent/v1/orders/{id}/payments/x402":{"post":{"tags":["Payments"],"operationId":"executeX402Payment","summary":"Issue or settle a provider-backed x402 v2 exact Base USDC payment","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"},"description":"Base64-encoded x402 v2 payload. Omit on the first request to receive PAYMENT-REQUIRED."}],"responses":{"200":{"description":"Settlement confirmed by the facilitator and independent Base receipt verification"},"202":{"description":"Submission is pending or ambiguous; do not initiate another payment"},"402":{"description":"PAYMENT-REQUIRED challenge returned"},"409":{"description":"Provider-pinned conflict or safe Review & Pay handoff","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SafeHandoffResponse"}}}}}}},"/api/agent/v1/orders/{id}/payments/mpp":{"post":{"tags":["Payments"],"operationId":"executeStripeMppPayment","summary":"Conditionally execute an approved single-use Stripe Shared Payment Token","security":[{"agentBearer":[],"dpop":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["credential"],"properties":{"credential":{"type":"object","required":["token"],"properties":{"token":{"type":"string","writeOnly":true,"pattern":"^spt_"}},"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"Stripe PaymentIntent succeeded"},"202":{"description":"Submission is pending or ambiguous; PAYAI will reconcile it"},"409":{"description":"Preview unavailable, policy failed, or human handoff required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SafeHandoffResponse"}}}}}}},"/api/agent/v1/orders/{id}/status":{"get":{"tags":["Orders"],"operationId":"getOrderStatus","summary":"Read order status with its bearer capability","security":[{"statusCapability":[]}],"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"Current commercial, payment, fulfilment and refund state"},"401":{"description":"Capability is missing"},"403":{"description":"Capability is invalid"}}}},"/api/track/{token}":{"get":{"tags":["Tracking"],"operationId":"getHumanOrderTracking","summary":"Read a redacted customer-safe order view","description":"The token is a separate, narrowly scoped capability embedded in the human tracking URL. It is not the agent status capability and cannot authorize checkout or payment.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","minLength":32,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"}}],"responses":{"200":{"description":"Safe order, payment, refund and fulfilment projections. Credentials, PII ciphertext, provider configuration and complete provider references are excluded."},"404":{"description":"Tracking capability is malformed or the order is unavailable"},"410":{"description":"Tracking capability is expired or invalid"}}}}},"components":{"securitySchemes":{"statusCapability":{"type":"http","scheme":"bearer","description":"Opaque capability returned exactly once when the order is created."},"agentBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Short-lived JWT from an explicitly allowlisted external issuer, bound to the agent key. PAYAI is not the token issuer. The verified issuer and subject, never an agentId JSON field or product name, establish identity."},"dpop":{"type":"apiKey","in":"header","name":"DPoP","description":"Fresh proof bound to the access token, method and exact request URL. Public client-certificate thumbprint headers are not trusted; this deployment does not accept mTLS-bound tokens without a trusted termination integration."}},"parameters":{"StorefrontSlug":{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},"ResourceId":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Unique operation key. Reuse with an identical request returns the original response; reuse with a different request returns 409."}},"schemas":{"SelectionLinkHandoff":{"type":"object","description":"Stateless, non-authoritative browser handoff. Query values may contain only public catalogue selections and public fulfilment hints; never include buyer, mandate, status, price, or payment data.","required":["version","template","supportsMultipleLines","allowsPrivateBuyerFields","authoritativeQuoteCreatedAtCheckout"],"properties":{"version":{"const":"1"},"template":{"type":"string","format":"uri-template","example":"https://localhost:3000/checkout/storefront?v=1&productId.0={productId}&quantity.0={quantity}"},"supportsMultipleLines":{"const":true},"maximumLines":{"type":"integer","const":20},"allowsPrivateBuyerFields":{"const":false},"authoritativeQuoteCreatedAtCheckout":{"const":true}},"additionalProperties":false},"StorefrontManifest":{"type":"object","required":["schemaVersion","kind","storefront","endpoints","handoff"],"properties":{"schemaVersion":{"type":"string"},"kind":{"const":"payai.storefront-manifest"},"storefront":{"type":"object","additionalProperties":true},"endpoints":{"type":"object","additionalProperties":true},"handoff":{"type":"object","required":["selectionLink","reviewAndPay","authorizedAgentPay"],"properties":{"selectionLink":{"$ref":"#/components/schemas/SelectionLinkHandoff"},"reviewAndPay":{"type":"object","additionalProperties":true},"authorizedAgentPay":{"type":"object","additionalProperties":true}}}},"additionalProperties":true},"ReviewAndPayAction":{"type":"object","required":["type","continueUrl","expiresAt"],"properties":{"type":{"const":"review_and_pay"},"continueUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}},"additionalProperties":false},"SubmitPaymentAction":{"type":"object","required":["type","rail","endpoint"],"properties":{"type":{"const":"submit_payment"},"rail":{"enum":["x402","stripe_mpp"]},"endpoint":{"type":"string","format":"uri"}},"additionalProperties":false},"PaymentPendingAction":{"type":"object","required":["type","attemptId"],"properties":{"type":{"const":"payment_pending"},"attemptId":{"type":"string"}},"additionalProperties":false},"CompleteAction":{"type":"object","required":["type"],"properties":{"type":{"const":"complete"}},"additionalProperties":false},"NextAction":{"oneOf":[{"$ref":"#/components/schemas/ReviewAndPayAction"},{"$ref":"#/components/schemas/SubmitPaymentAction"},{"$ref":"#/components/schemas/PaymentPendingAction"},{"$ref":"#/components/schemas/CompleteAction"}]},"OrderTracking":{"type":"object","required":["orderId","statusUrl","statusCapability"],"properties":{"orderId":{"type":"string"},"statusUrl":{"type":"string","format":"uri"},"statusCapability":{"type":"string","format":"password","description":"Opaque bearer capability returned once. Keep it secret and send it only to the order-bound status endpoint."},"humanUrl":{"type":"string","format":"uri","description":"Customer-safe tracking page containing a distinct, narrowly scoped bearer capability."},"humanUrlExpiresAt":{"type":"string","format":"date-time"}},"additionalProperties":false},"OrderActionResponse":{"type":"object","required":["order","statusCapability","nextAction","fallback","tracking"],"properties":{"order":{"$ref":"#/components/schemas/Order"},"statusCapability":{"type":"string","format":"password","description":"Opaque bearer capability; keep secret."},"capabilityToken":{"type":"string","format":"password","deprecated":true,"description":"Compatibility alias for statusCapability; keep secret."},"continueUrl":{"type":"string","format":"uri","deprecated":true},"continueUrlExpiresAt":{"type":"string","format":"date-time","deprecated":true},"nextAction":{"$ref":"#/components/schemas/NextAction"},"fallback":{"$ref":"#/components/schemas/ReviewAndPayAction"},"tracking":{"$ref":"#/components/schemas/OrderTracking"}},"additionalProperties":true},"SafeHandoffResponse":{"type":"object","required":["nextAction","fallback"],"properties":{"nextAction":{"$ref":"#/components/schemas/ReviewAndPayAction"},"fallback":{"$ref":"#/components/schemas/ReviewAndPayAction"},"tracking":{"type":"object","required":["orderId","statusUrl"],"properties":{"orderId":{"type":"string"},"statusUrl":{"type":"string","format":"uri"},"humanUrl":{"type":"string","format":"uri"},"humanUrlExpiresAt":{"type":"string","format":"date-time"}}}},"additionalProperties":true},"Money":{"type":"object","required":["amountMinor","currency"],"properties":{"amountMinor":{"type":"string","pattern":"^-?[0-9]+$"},"currency":{"type":"string","pattern":"^[A-Z]{3,8}$"}}},"QuoteSelection":{"type":"object","required":["productId","quantity"],"properties":{"productId":{"type":"string"},"variantId":{"type":"string"},"modifierIds":{"type":"array","items":{"type":"string"}},"quantity":{"type":"integer","minimum":1,"maximum":1000}},"additionalProperties":false},"QuoteRequest":{"type":"object","required":["selections","fulfilment"],"properties":{"selections":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/QuoteSelection"}},"requestedCurrency":{"type":"string","pattern":"^[A-Z]{3,8}$","description":"USDC is accepted only where the seller publishes a direct USDC price; PAYAI does not perform FX."},"destination":{"type":"object","required":["country"],"properties":{"country":{"type":"string"},"subdivision":{"type":"string"},"postalCode":{"type":"string"}}},"shippingAddress":{"type":"object","required":["name","line1","locality","postalCode","country"],"properties":{"name":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"locality":{"type":"string"},"subdivision":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"additionalProperties":false},"deliveryEmail":{"type":"string","format":"email"},"fulfilment":{"type":"object","required":["method"],"properties":{"method":{"type":"string"},"locationId":{"type":"string"},"requestedAt":{"type":"string","format":"date-time"}}},"buyerFields":{"type":"object","additionalProperties":{"type":"string"}}},"additionalProperties":false},"OrderRequest":{"type":"object","properties":{"buyerFields":{"type":"object","additionalProperties":{"type":"string"}},"buyerAuthorizationId":{"type":"string"},"requestedPaymentOption":{"enum":["x402_base_usdc","stripe_checkout","stripe_mpp_spt","mollie_checkout","paypal_checkout","manual_bank"]},"requestedMode":{"enum":["human","exact_approval","preauthorized"],"default":"human"}},"additionalProperties":false},"Quote":{"type":"object","required":["id","status","lines","total","expiresAt"],"properties":{"id":{"type":"string"},"status":{"enum":["OPEN","EXPIRED","CONVERTED"]},"lines":{"type":"array","items":{"type":"object"}},"total":{"$ref":"#/components/schemas/Money"},"expiresAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"Order":{"type":"object","required":["id","commercialState","paymentState","fulfilmentState"],"properties":{"id":{"type":"string"},"commercialState":{"type":"string"},"paymentState":{"type":"string"},"fulfilmentState":{"type":"string"},"refundState":{"type":"string"},"quote":{"$ref":"#/components/schemas/Quote"}},"additionalProperties":true},"Error":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}},"requestId":{"type":"string"}}}},"responses":{"Conflict":{"description":"The resource state or idempotency binding conflicts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"Request validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}