openapi: 3.2.0 info: title: MandateShield Payment Authority Production authority API version: 3.4.0 description: Fail-closed authority verification, provider-bound execution permits and provider-outcome reconciliation that is caller-report-independent for autonomous AI-agent purchases. termsOfService: https://mandateshield.com/terms contact: name: Gökhan Vodinali · MandateShield operator url: https://mandateshield.com/legal email: support@hemelion.com servers: - url: https://mandateshield.com tags: - name: Production authority description: Challenge, strict verification, and processor transitions. The documented eight-field invariant establishes only a RESERVED, consumable authorization; a trusted gateway must obtain the single winning PROCESSOR-scoped CONSUME transition and fresh permit claim before attempting an idempotent provider request. MandateShield does not guarantee exactly-once provider delivery. paths: /api/v2/challenges: post: operationId: createVerificationChallenge tags: - Production authority summary: Issue a one-time challenge for a registered mandate description: Requires an active live key, a current business-agreement acceptance, an active account-registered mandate and the RFC 7638 thumbprint of an active account-pinned payment-authority key. The nonce expires after five minutes and is consumable once for the same account, mandate, protocol and pinned key. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChallengeRequest' example: mandate_id: mnd_2048 protocol: AP2 key_thumbprint: xT6OvMVxNPaVQpsUQ9gH3JqP0YgKxF2Q3fJ2aK9vQmI responses: '201': description: Challenge issued content: application/json: schema: $ref: '#/components/schemas/Challenge' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': description: The account is not eligible for live challenges content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No active registered mandate matches mandate_id content: application/json: schema: $ref: '#/components/schemas/Error' '413': $ref: '#/components/responses/TooLarge' '428': $ref: '#/components/responses/LegalAcceptanceRequired' /api/v2/verify: post: operationId: verifyCryptographicAuthority tags: - Production authority summary: Verify signed purchase authority and issue a signed receipt description: 'A qualifying live ALLOW requires an active VERIFY-scoped live key, registered mandate, account-pinned key, exact signed issuer/audience/protocol, fresh one-time challenge, signed freshness, exact purchase binding, durable replay state, signed receipt, public transparency record, private execution audit, a RUNNING account-wide execution interlock and an atomically RESERVED cumulative-budget authorization. The response is not permission to submit directly: a trusted gateway must use a separate PROCESSOR-scoped key to obtain the single winning CONSUME transition and a fresh exact-bound permit claim, then attempt an idempotent provider request. These MandateShield state transitions do not guarantee exactly-once provider delivery. Anonymous and test calls can inspect cryptographic behavior but are never executable.' security: - bearerAuth: [] - {} requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StrictVerificationInput' examples: jws: summary: Compact JWS bound to a final purchase value: envelope: protocol: CUSTOM mandate_id: mnd_2048 agent_id: agent_travel_07 merchant_id: merchant_rail amount: value: 124.9 currency: USD created_at: idempotency_key: order_9f22a1 checkout_hash: sha256:example-checkout intent_hash: sha256:example credential_binding: issuer:travel-authority:agent_travel_07 evidence: format: jws compact: eyJhbGciOiJFUzI1NiIsImtpZCI6Ii4uLiJ9.eyJpc3MiOiIuLi4ifQ.signature public_key: kty: EC crv: P-256 x: base64url-x y: base64url-y x402Atomic: summary: Signed verification projection for an x402 atomic-asset purchase description: atomic_units remains an exact decimal string. MandateShield verifies this pre-payment projection; it does not create or submit an x402 payment payload. value: envelope: protocol: X402 mandate_id: mnd_api_access_2048 agent_id: agent_research_07 merchant_id: merchant_data_api amount: atomic_units: '900719925474099312345678901' asset_decimals: 6 asset_id: eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 network: eip155:8453 resource: https://api.example.test/v1/research/report-7 created_at: idempotency_key: x402_report_7_attempt_1 intent_hash: sha256:example-x402-intent credential_binding: issuer:payment-authority:agent_research_07 evidence: format: jws compact: eyJhbGciOiJFUzI1NiIsImtpZCI6Ii4uLiJ9.eyJpc3MiOiIuLi4ifQ.signature public_key: kty: EC crv: P-256 x: base64url-x y: base64url-y responses: '200': description: Verification completed. Inspect every execution-invariant field; HTTP 200 is not authorization. content: application/json: schema: $ref: '#/components/schemas/StrictDecision' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': description: Production access is paused content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Sequential or concurrent payment replay blocked content: application/json: schema: oneOf: - $ref: '#/components/schemas/StrictDecision' - $ref: '#/components/schemas/Error' '413': $ref: '#/components/responses/TooLarge' '423': description: The account-wide execution interlock is PAUSED or failed closed; no new MandateShield-mediated reservation was created content: application/json: schema: $ref: '#/components/schemas/Error' '428': $ref: '#/components/responses/LegalAcceptanceRequired' '429': description: Anonymous or test allowance exceeded content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Signed receipt or a persistence record required for execution could not be committed content: application/json: schema: $ref: '#/components/schemas/Error' /api/v2/execution-authorizations: post: operationId: transitionExecutionAuthorization tags: - Production authority summary: Atomically transition one reserved execution authorization description: Processor integration endpoint. Every account created at or after 2026-07-26T12:01:24.000Z must supply provider_binding for CONSUME; only accounts created before that cutoff retain legacy unbound CONSUME compatibility. A missing or malformed account creation timestamp fails closed as a new account. CONSUME additionally requires the account-wide execution interlock to be RUNNING in the same atomic transaction; COMMIT, RELEASE and EXPIRE remain available while PAUSED. Provider-bound CONSUME atomically creates a ProviderSubmission record, stores and returns a signed execution_permit, sets provider_submission_permitted=false and provider_redemption_required=true, and requires the exact audience-bound execution service to claim that permit online before submission. Offline verification never grants submission. A qualifying legacy unbound CONSUME can return provider_submission_permitted=true only for a fresh non-replayed transition. Manual COMMIT or RELEASE accepts a caller-asserted processor_result and produces CALLER_ASSERTED evidence. A terminal transition may instead bind one canonical provider_evidence_id that MandateShield checked without trusting the caller assertion. The hosted reconciliation worker uses that strong evidence to autonomously COMMIT or RELEASE and issue a receipt whose legacy field independent_verification=true means independent of caller assertion, not an independent organization. Unknown or conflicting outcomes remain fail-closed and conservatively charged. Publication does not establish external provider adoption or PROVIDER_ENFORCED status. x-mandateshield-provider-binding-policy: required_for_accounts_created_at_or_after: '2026-07-26T12:01:24.000Z' legacy_unbound_consume_allowed_only_for_accounts_created_before: '2026-07-26T12:01:24.000Z' missing_account_creation_time_fails_closed: true security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExecutionAuthorizationTransitionRequest' responses: '200': description: Transition committed, or the exact idempotent result replayed content: application/json: schema: $ref: '#/components/schemas/ExecutionAuthorizationTransitionResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': description: New consumption is blocked for an inactive account content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: A paid live processor key is required content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Binding mismatch, malformed provider binding, reused idempotency key, illegal state, processor-result mismatch, or concurrent transition content: application/json: schema: $ref: '#/components/schemas/Error' '410': description: The unconsumed execution window elapsed content: application/json: schema: $ref: '#/components/schemas/Error' '413': $ref: '#/components/responses/TooLarge' '422': description: provider_binding is absent for a CONSUME on an account subject to the provider-bound default content: application/json: schema: $ref: '#/components/schemas/Error' '423': description: CONSUME was withheld by the account-wide execution interlock; terminal evidence transitions remain available content: application/json: schema: $ref: '#/components/schemas/Error' '428': description: CONSUME requires the account's current business-agreement acceptance; COMMIT, RELEASE and EXPIRE remain available for existing state content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Processor transition rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: The atomic transition is unavailable content: application/json: schema: $ref: '#/components/schemas/Error' /api/v2/batch: post: operationId: verifyCryptographicAuthorityBatch tags: - Production authority summary: Verify 1–25 distinct strict authority inputs description: Every item uses the complete v2 verifier and requires its own idempotency key and unconsumed challenge for live authorization. Authenticated live items also require the account's current business-agreement acceptance and can return LEGAL_ACCEPTANCE_REQUIRED as an item status. The outer HTTP result never authorizes the batch. security: - bearerAuth: [] - {} requestBody: required: true content: application/json: schema: oneOf: - type: array minItems: 1 maxItems: 25 items: $ref: '#/components/schemas/StrictVerificationInput' - type: object additionalProperties: false required: - purchases properties: purchases: type: array minItems: 1 maxItems: 25 items: $ref: '#/components/schemas/StrictVerificationInput' responses: '200': description: Ordered per-item results and non-normative summary content: application/json: schema: $ref: '#/components/schemas/StrictBatchResponse' '400': $ref: '#/components/responses/BadRequest' '413': $ref: '#/components/responses/TooLarge' components: schemas: PublicVerificationJwk: type: object description: Public signature-verification JWK. The release profile supports P-256 with ES256 and 2048–8192 bit RSA with RS256 or PS256. Registration and request verification use the same strict validation and import gate. A request-supplied key is not a trust anchor; live authorization requires an exact account pin. required: - kty properties: kty: type: string enum: - EC - RSA use: const: sig key_ops: type: array minItems: 1 maxItems: 1 uniqueItems: true items: const: verify alg: type: string enum: - ES256 - RS256 - PS256 kid: type: string crv: type: string x: type: string y: type: string n: type: string e: type: string allOf: - not: anyOf: - required: - d - required: - p - required: - q - required: - dp - required: - dq - required: - qi - required: - oth - required: - k - if: properties: kty: const: EC required: - kty then: required: - crv - x - y properties: alg: const: ES256 crv: const: P-256 - if: properties: kty: const: RSA required: - kty then: required: - n - e properties: alg: enum: - RS256 - PS256 Finding: type: object additionalProperties: false required: - code - message - severity properties: code: type: string message: type: string severity: type: string enum: - high - medium - low StrictDecision: allOf: - $ref: '#/components/schemas/PreflightDecision' - type: object required: - assurance - signed_receipt - transparency - execution_authorization properties: assurance: $ref: '#/components/schemas/EvidenceAssurance' signed_receipt: $ref: '#/components/schemas/SignedDecisionReceipt' transparency: $ref: '#/components/schemas/TransparencyStatus' execution_authorization: $ref: '#/components/schemas/ExecutionAuthorizationReservation' StrictBatchResponse: type: object additionalProperties: false required: - summary - results properties: summary: type: object additionalProperties: false required: - total - enforcement_authorized - allowed - reviewed - blocked - errors properties: total: type: integer minimum: 1 maximum: 25 enforcement_authorized: type: integer minimum: 0 allowed: type: integer minimum: 0 reviewed: type: integer minimum: 0 blocked: type: integer minimum: 0 errors: type: integer minimum: 0 results: type: array minItems: 1 maxItems: 25 items: type: object required: - index - status - result properties: index: type: integer minimum: 0 maximum: 24 status: type: integer minimum: 100 maximum: 599 result: oneOf: - $ref: '#/components/schemas/StrictDecision' - $ref: '#/components/schemas/Error' LegalAcceptanceRequiredError: type: object additionalProperties: false required: - error - code - terms_version - acceptance_url properties: error: type: string code: const: LEGAL_ACCEPTANCE_REQUIRED terms_version: type: string const: 2026-07-28.2 acceptance_url: type: string format: uri const: https://mandateshield.com/dashboard?legal=required CryptographicEvidence: type: object additionalProperties: false description: JWS, an AP2-shaped closed-payment SD-JWT projection with RFC 9901 KB-JWT, or normalized TAP-shaped RFC 9421-style evidence. AP2 checkout_jwt hash, delegate chain, open-mandate and issuer-registry checks plus Visa TAP structured-field/trust-store processing remain external. required: - format - public_key properties: format: type: string enum: - jws - sd-jwt - http-message-signature compact: type: string description: Compact JWS or SD-JWT serialization. public_key: $ref: '#/components/schemas/PublicVerificationJwk' expected_audience: type: string description: Optional additional check. The account-pinned audience remains authoritative in production. expected_nonce: type: string description: Optional additional check. Production consumes the signed server challenge as a separate single-winner state transition. expected_authority: type: string algorithm: type: string enum: - ES256 - RS256 - PS256 signature: type: string signature_input: $ref: '#/components/schemas/HttpSignatureInput' components: type: object additionalProperties: type: string allOf: - if: properties: format: enum: - jws - sd-jwt then: required: - compact - if: properties: format: const: http-message-signature then: required: - algorithm - signature - signature_input - components ProviderEvidenceClass: type: string enum: - CALLER_ASSERTED - FACILITATOR_SIGNED - PROVIDER_API_VERIFIED - CHAIN_FINALIZED - UNRESOLVED - LEDGER_DERIVED description: PROVIDER_API_VERIFIED and CHAIN_FINALIZED are the current hosted terminal evidence classes checked without trusting the caller report. FACILITATOR_SIGNED is a retained evidence class for separately configured integrations and does not imply current provider/facilitator adoption. No class claims verification by an independent organization, audit or certification. LEDGER_DERIVED is used by execution receipts, not ProviderEvidence rows. PreflightDecision: type: object required: - decision - score - receipt - checked_at - protocol - findings - risk - recommended_action - controls - mode - persisted - enforcement_authorized properties: decision: type: string enum: - ALLOW - REVIEW - BLOCK policy_decision: type: string enum: - ALLOW - REVIEW - BLOCK score: type: integer minimum: 0 maximum: 100 description: Deterministic control-coverage indicator, not a calibrated probability of fraud or loss. receipt: type: string pattern: ^sha256:[a-f0-9]{64}$ checked_at: type: string format: date-time protocol: type: string findings: type: array items: $ref: '#/components/schemas/Finding' risk: $ref: '#/components/schemas/Risk' recommended_action: type: string controls: type: object required: - evaluated - passed properties: evaluated: type: integer minimum: 0 passed: type: integer minimum: 0 mode: type: string enum: - sandbox - test - live - strict persisted: type: boolean enforcement_authorized: type: boolean description: Always false for v1. In strict v2, true means a short-lived execution reservation committed atomically; an integrating processor must still obtain the single winning CONSUME transition and fresh exact-bound permit claim before an idempotent provider request. MandateShield does not guarantee exactly-once provider delivery. mandate: oneOf: - $ref: '#/components/schemas/MandateBinding' - type: 'null' EvidenceAssurance: type: object required: - status - signature_valid - authority_valid - format - algorithm - key_id - key_trust - key_thumbprint - issuer - audiences - nonce - issued_at - expires_at - input_digest - claims_digest - findings properties: status: type: string enum: - VERIFIED - REJECTED signature_valid: type: boolean authority_valid: type: boolean format: type: string algorithm: type: - string - 'null' key_id: type: - string - 'null' key_trust: type: string enum: - CALLER_SUPPLIED - ACCOUNT_PINNED key_thumbprint: type: - string - 'null' issuer: type: - string - 'null' audiences: type: array items: type: string nonce: type: - string - 'null' issued_at: type: - integer - 'null' expires_at: type: - integer - 'null' input_digest: type: string pattern: ^sha256:[a-f0-9]{64}$ claims_digest: type: - string - 'null' pattern: ^sha256:[a-f0-9]{64}$ findings: type: array items: $ref: '#/components/schemas/Finding' StrictVerificationInput: type: object additionalProperties: false required: - envelope - evidence properties: envelope: $ref: '#/components/schemas/PurchaseEnvelope' evidence: $ref: '#/components/schemas/CryptographicEvidence' HttpSignatureInput: type: object additionalProperties: false required: - covered_components - nonce - created - expires - keyid properties: covered_components: type: array minItems: 4 items: type: string nonce: type: string created: type: integer expires: type: integer keyid: type: string tag: type: string ChallengeRequest: type: object additionalProperties: false required: - mandate_id - protocol - key_thumbprint properties: mandate_id: type: string minLength: 1 protocol: type: string enum: - AP2 - TAP - UCP - X402 - MPP - ACP - CUSTOM description: Exact protocol for this challenge. ANY is valid only when registering a trust-key pin. key_thumbprint: type: string pattern: ^[A-Za-z0-9_-]{43}$ description: RFC 7638 thumbprint of the account-pinned payment-authority key. ProviderBindingInput: type: object additionalProperties: false required: - profile - environment - account - request_id - payee_destination - method - resource - body_digest properties: profile: type: string enum: - GENERIC_HTTP_V1 - STRIPE_PAYMENT_INTENTS_V1 - X402_V2_EXACT - MPP_CHARGE_V1 environment: type: string enum: - test - live account: type: string minLength: 1 maxLength: 240 request_id: type: string minLength: 1 maxLength: 240 payee_destination: type: string minLength: 1 maxLength: 500 description: Must exactly equal expected_envelope.merchant_id or a provider destination carried by its canonical signed payee_identity. The provider profile must match that identity. MandateShield binds this value but does not independently resolve or certify a PSP account. method: type: string enum: - GET - POST - PUT - PATCH resource: type: string format: uri pattern: ^https:// maxLength: 2048 description: Canonical absolute HTTPS URI without credentials or a fragment. body_digest: type: string pattern: ^sha256:[a-f0-9]{64}$ description: Optional only for CONSUME. Requests a portable provider-bound permit rather than direct legacy gateway submission permission. Risk: type: object required: - level - requested_value - mandate_headroom - blocked_value - primary_reason properties: level: type: string enum: - CLEAR - GUARDED - ELEVATED - CRITICAL requested_value: type: - number - 'null' mandate_headroom: type: - number - 'null' blocked_value: type: number minimum: 0 primary_reason: type: - string - 'null' SignedExecutionReceipt: type: object additionalProperties: false required: - format - compact - execution_receipt_id - key_id - jwks_uri - verify_uri - historical_evidence_only - execution_authorized - evidence_class - independent_verification properties: format: const: application/mandateshield-execution-receipt+jwt compact: type: string minLength: 1 maxLength: 20000 execution_receipt_id: type: string pattern: ^mse_[a-f0-9]{32}$ key_id: type: string minLength: 1 maxLength: 240 jwks_uri: const: https://mandateshield.com/.well-known/jwks.json verify_uri: const: https://mandateshield.com/api/v2/execution-receipts/verify historical_evidence_only: const: true execution_authorized: const: false evidence_class: $ref: '#/components/schemas/ProviderEvidenceClass' independent_verification: type: boolean description: Legacy field name. True means configured evidence was checked without trusting the caller report; it does not mean verification by an independent organization, audit, certification, or provider adoption. description: Historical terminal-state evidence. The signed artifact never grants a new provider submission and does not upgrade the evidence_class. ProcessorResult: type: object additionalProperties: false required: - payment_reference - outcome - payee - audience - occurred_at - amount properties: payment_reference: type: string minLength: 1 maxLength: 240 description: Non-secret processor attempt/reference. It cannot be reused for another authorization under the same account and authenticated processor_audience. outcome: type: string enum: - COMMITTED - NOT_SUBMITTED - FAILED payee: type: string description: Must exactly match the authorized merchant_id. audience: type: string description: Must exactly match the pinned relying-party audience. occurred_at: type: string format: date-time amount: oneOf: - type: object additionalProperties: false required: - minor_units - currency properties: minor_units: type: integer minimum: 1 currency: type: string pattern: ^[A-Z]{3}$ - type: object additionalProperties: false required: - atomic_units - asset_decimals - asset_id - network - resource properties: atomic_units: type: string pattern: ^(?:0|[1-9][0-9]{0,77})$ asset_decimals: type: integer minimum: 0 maximum: 30 asset_id: type: string network: type: string resource: type: string description: Caller-asserted processor outcome authenticated by the live API key and stored as a canonical digest plus bounded non-secret reference. Processor identity is derived from that key's processor_audience and cannot be supplied in this object. It is not provider evidence checked without trusting the caller. Challenge: type: object additionalProperties: false required: - nonce - created_at - expires_at - mandate_id - mandate_version - mandate_hash - protocol - key_thumbprint - issuer - audience - expires_at_iso properties: nonce: type: string created_at: type: integer description: Unix milliseconds expires_at: type: integer description: Unix milliseconds mandate_id: type: string mandate_version: type: integer minimum: 1 mandate_hash: type: string pattern: ^sha256:[a-f0-9]{64}$ protocol: type: string key_thumbprint: type: string pattern: ^[A-Za-z0-9_-]{43}$ issuer: type: string minLength: 1 description: Issuer registered with the selected key pin. Sign this exact value. audience: type: string minLength: 1 description: Audience registered with the selected key pin. Sign this exact value. expires_at_iso: type: string format: date-time SignedExecutionPermit: type: object additionalProperties: false required: - format - compact - permit_id - key_id - jwks_uri - verify_uri - redemption_uri - expires_at - online_redemption_required - offline_one_use_enforced properties: format: const: application/mandateshield-execution-permit+jwt compact: type: string minLength: 1 maxLength: 20000 permit_id: type: string pattern: ^msp_[a-f0-9]{32}$ key_id: type: string minLength: 1 maxLength: 240 jwks_uri: const: https://mandateshield.com/.well-known/jwks.json verify_uri: const: https://mandateshield.com/api/v2/execution-permits/verify redemption_uri: const: https://mandateshield.com/api/v2/execution-permits/redeem expires_at: type: integer minimum: 1 description: JWT NumericDate in whole Unix seconds. online_redemption_required: const: true offline_one_use_enforced: const: false description: Portable cryptographic permit. It is not a bearer proof of unused state and never authorizes direct provider submission without a fresh online claim. ProviderSubmissionId: type: string pattern: ^psub_[a-f0-9]{32}$ Error: type: object required: - error properties: error: type: string code: type: string enforcement_authorized: type: boolean ExecutionAuthorizationState: type: string enum: - RESERVED - CONSUMED - COMMITTED - RELEASED - EXPIRED - SETTLEMENT_UNKNOWN - NOT_RESERVED - ARCHIVAL_ONLY PurchaseEnvelope: type: object additionalProperties: true required: - protocol - mandate_id - agent_id - merchant_id - amount - idempotency_key properties: protocol: type: string enum: - AP2 - TAP - UCP - X402 - MPP - ACP - CUSTOM mandate_id: type: string minLength: 1 agent_id: type: string minLength: 1 merchant_id: type: string minLength: 1 payee_identity: type: object additionalProperties: false required: - profile - provider - merchant_id - binding - verification properties: profile: const: MANDATESHIELD_PAYEE_IDENTITY_V1 provider: type: string enum: - X402 - MPP - STRIPE - CUSTOM merchant_id: type: string minLength: 1 maxLength: 240 binding: type: object verification: type: object additionalProperties: false required: - method - verifier - evidence_ref properties: method: type: string enum: - TRUSTED_MERCHANT_MAPPING - TLS_SERVICE_ORIGIN - STRIPE_ACCOUNT_CONFIGURATION - HTTPS_WELL_KNOWN verifier: type: string minLength: 1 maxLength: 240 evidence_ref: type: string minLength: 1 maxLength: 2048 oneOf: - properties: provider: const: X402 binding: type: object additionalProperties: false required: - network - pay_to properties: network: type: string minLength: 1 maxLength: 240 pay_to: type: string minLength: 1 maxLength: 500 verification: type: object additionalProperties: false required: - method - verifier - evidence_ref properties: method: const: TRUSTED_MERCHANT_MAPPING verifier: type: string minLength: 1 maxLength: 240 evidence_ref: type: string minLength: 1 maxLength: 2048 - properties: provider: const: MPP binding: type: object additionalProperties: false required: - service_origin - method properties: service_origin: type: string pattern: ^https://[^/?#]+$ method: type: string pattern: ^[a-z]+$ verification: type: object additionalProperties: false required: - method - verifier - evidence_ref properties: method: const: TLS_SERVICE_ORIGIN verifier: type: string minLength: 1 maxLength: 240 evidence_ref: type: string minLength: 1 maxLength: 2048 - properties: provider: const: STRIPE binding: type: object additionalProperties: false required: - connected_account_id - merchant_account_id properties: connected_account_id: type: string pattern: ^acct_[A-Za-z0-9_]{8,240}$ merchant_account_id: type: string pattern: ^acct_[A-Za-z0-9_]{8,240}$ verification: type: object additionalProperties: false required: - method - verifier - evidence_ref properties: method: const: STRIPE_ACCOUNT_CONFIGURATION verifier: type: string minLength: 1 maxLength: 240 evidence_ref: type: string pattern: ^urn:stripe:connected-account:acct_[A-Za-z0-9_]{8,240}$ - properties: provider: const: CUSTOM binding: type: object additionalProperties: false required: - service_origin - provider_id properties: service_origin: type: string pattern: ^https://[^/?#]+$ provider_id: type: string minLength: 1 maxLength: 240 verification: type: object additionalProperties: false required: - method - verifier - evidence_ref properties: method: const: HTTPS_WELL_KNOWN verifier: type: string minLength: 1 maxLength: 240 evidence_ref: type: string format: uri pattern: ^https://[^/?#]+/\.well-known/mandateshield-payee\.json$ description: Versioned canonical payee identity bound into the signed purchase envelope. The model records exact provider identifiers and verification evidence; it does not independently validate an external registry, TLS session, provider account or domain-control document. amount: type: object additionalProperties: false oneOf: - required: - value - currency - required: - atomic_units - asset_decimals properties: value: type: number exclusiveMinimum: 0 minor_units: type: integer description: Optional exact integer minor-unit amount. Must agree with value. currency: type: string pattern: ^[A-Za-z]{3}$ description: Current ISO 4217 code with numeric minor units. atomic_units: type: string pattern: ^(?:0|[1-9][0-9]{0,77})$ description: Exact canonical atomic-asset integer string. It is authoritative for X402 and compared to the registered cap with BigInt semantics; never send a JSON number, decimal, sign or exponent. asset_decimals: type: integer minimum: 0 maximum: 30 description: Exact asset exponent from 0 through 30. For X402 it must equal the registered mandate value; it is not inferred from atomic_units. limits: type: object additionalProperties: true description: Sandbox analysis policy only. Live v2 ignores caller-supplied limits and injects the active registered mandate. properties: max_amount: type: number exclusiveMinimum: 0 description: Analysis convenience field in major units. max_amount_minor: type: integer exclusiveMinimum: 0 description: Exact registered production ceiling in currency minor units. max_atomic_units: type: string pattern: ^[1-9][0-9]{0,77}$ description: Exact positive canonical atomic-unit ceiling. Production obtains this string from the registered mandate and compares it without floating-point conversion. asset_decimals: type: integer minimum: 0 maximum: 30 description: Registered atomic-asset exponent; the request must match it exactly. currencies: type: array minItems: 1 items: type: string pattern: ^[A-Za-z]{3}$ merchants: type: array minItems: 1 items: type: string minLength: 1 assets: type: array minItems: 1 items: type: string minLength: 1 description: Exact allowed asset identifiers for sandbox analysis. networks: type: array minItems: 1 items: type: string minLength: 1 description: Exact allowed network identifiers for sandbox analysis. resources: type: array minItems: 1 items: type: string minLength: 1 description: Exact allowed paid-resource identifiers for sandbox analysis. oneOf: - required: - currencies - merchants anyOf: - required: - max_amount_minor - required: - max_amount - required: - max_atomic_units - asset_decimals - assets - networks - resources - merchants asset_id: type: string minLength: 1 description: Exact token or asset identifier. Required for X402 and matched byte-for-byte to the registered mandate after surrounding whitespace is removed. network: type: string minLength: 1 description: Exact network or chain identifier. Required for X402 and matched to the registered mandate. resource: type: string minLength: 1 description: Exact paid-resource identifier. Required for X402 and matched to the registered mandate; a different path or resource is a substitution. http_request: type: object additionalProperties: false required: - profile - url - method - body_sha256 - headers_sha256 - redirect_policy properties: profile: const: MANDATESHIELD_X402_V2_EXACT_EIP3009_V1 url: type: string format: uri method: type: string enum: - GET - HEAD - POST - PUT - PATCH - DELETE body_sha256: type: string pattern: ^sha256:[a-f0-9]{64}$ headers_sha256: type: string pattern: ^sha256:[a-f0-9]{64}$ redirect_policy: const: ERROR description: Optional signed HTTP action projection used by the narrow first-party x402 v2 exact/EIP-3009 Gate adapter. created_at: type: string format: date-time expires_at: type: string format: date-time idempotency_key: type: string minLength: 1 maxLength: 256 pattern: ^[A-Za-z0-9._:~-]+$ intent_hash: type: string checkout_hash: type: string minLength: 1 description: Digest or stable identifier for the exact final checkout. Required by the strict AP2 closed-payment projection. user_consent: type: boolean credential_binding: type: string purpose: type: string description: Normalized purchase facts for policy and authority verification. For X402 this is a pre-payment verification projection, not an x402 challenge, signed payment payload, facilitator submission or settlement instruction. allOf: - if: properties: protocol: const: X402 required: - protocol then: required: - asset_id - network - resource properties: amount: required: - atomic_units - asset_decimals ProviderEvidenceId: type: string pattern: ^pevd_[a-f0-9]{32}$ ExecutionAuthorizationTransitionRequest: type: object additionalProperties: false required: - action - compact - idempotency_key - expected_envelope - expected_audience properties: action: type: string enum: - CONSUME - COMMIT - RELEASE - EXPIRE compact: type: string maxLength: 20000 description: The signed_receipt.compact value returned by strict v2; it is the signed authorization token. idempotency_key: type: string pattern: ^[A-Za-z0-9._:~-]{1,256}$ expected_envelope: $ref: '#/components/schemas/PurchaseEnvelope' expected_audience: type: string minLength: 1 maxLength: 240 processor_result: $ref: '#/components/schemas/ProcessorResult' provider_evidence_id: $ref: '#/components/schemas/ProviderEvidenceId' description: Canonical ProviderEvidence row checked without trusting the caller report. Accepted only for COMMIT or RELEASE and mutually exclusive with processor_result. provider_binding: $ref: '#/components/schemas/ProviderBindingInput' description: Required for CONSUME when the account was created at or after 2026-07-26T12:01:24.000Z. Omission is retained only for accounts created before that cutoff. allOf: - if: properties: action: enum: - COMMIT - RELEASE required: - action then: properties: provider_binding: false oneOf: - required: - processor_result properties: provider_evidence_id: false - required: - provider_evidence_id properties: processor_result: false - if: properties: action: enum: - CONSUME - EXPIRE required: - action then: properties: processor_result: false provider_evidence_id: false - if: properties: action: const: EXPIRE required: - action then: properties: provider_binding: false SignedDecisionReceipt: type: object additionalProperties: false required: - format - compact - receipt_id - key_id - jwks_uri - verify_uri - transparency_uri - execution_authorization_uri properties: format: const: application/mandateshield-receipt+jwt compact: type: string receipt_id: type: string pattern: ^msr_[a-f0-9]{32}$ key_id: type: string jwks_uri: const: https://mandateshield.com/.well-known/jwks.json verify_uri: const: https://mandateshield.com/api/v2/receipts/verify transparency_uri: type: string pattern: ^https://mandateshield\.com/api/v2/transparency/msr_[a-f0-9]{32}$ execution_authorization_uri: const: https://mandateshield.com/api/v2/execution-authorizations ExecutionAuthorizationTransitionResult: type: object additionalProperties: false required: - receipt_id - action - transition_state - current_state - transitioned_at - expires_at - settlement_deadline_at - idempotent_replay - processor_result_recorded - independent_verification - provider_evidence_id - evidence_class - processor_audience - payment_reference - provider_submission_permitted - provider_redemption_required - processor_integration_required - execution_permit - provider_submission_id - execution_receipt properties: receipt_id: type: string pattern: ^msr_[a-f0-9]{32}$ action: type: string enum: - CONSUME - COMMIT - RELEASE - EXPIRE - SETTLE_UNKNOWN transition_state: $ref: '#/components/schemas/ExecutionAuthorizationState' current_state: $ref: '#/components/schemas/ExecutionAuthorizationState' transitioned_at: type: integer description: Unix milliseconds expires_at: type: integer description: Unix milliseconds settlement_deadline_at: type: - integer - 'null' description: Unix milliseconds. Set by CONSUME. It is the cutoff for a new provider submission and for RELEASE; a canonically confirmed COMMIT may still arrive later. Afterward an unresolved settlement is conservatively charged to the budget. idempotent_replay: type: boolean processor_result_recorded: type: boolean independent_verification: type: boolean description: True only for a terminal COMMIT or RELEASE bound to strong configured evidence checked without trusting the caller report. It does not claim an independent organization, audit or certification. provider_evidence_id: oneOf: - $ref: '#/components/schemas/ProviderEvidenceId' - type: 'null' evidence_class: oneOf: - $ref: '#/components/schemas/ProviderEvidenceClass' - type: 'null' processor_audience: type: - string - 'null' payment_reference: type: - string - 'null' provider_submission_permitted: type: boolean description: 'Pre-2026-07-26T12:01:24.000Z legacy-account path only: true exclusively for a newly committed CONSUME without provider_binding whose current state is CONSUMED. All accounts created at or after the cutoff require provider_binding. This field is false for permit issuance, every replay and every terminal transition; a permit must instead be atomically redeemed by the exact audience-bound integration.' provider_redemption_required: type: boolean description: True exactly when CONSUME issued execution_permit. In that path provider_submission_permitted is false until the separate redemption endpoint performs a fresh ISSUED-to-CLAIMED transition. processor_integration_required: const: true execution_permit: oneOf: - $ref: '#/components/schemas/SignedExecutionPermit' - type: 'null' provider_submission_id: oneOf: - $ref: '#/components/schemas/ProviderSubmissionId' - type: 'null' description: Created atomically with a provider-bound execution permit and returned on its transition. Null for legacy unbound execution. execution_receipt: oneOf: - $ref: '#/components/schemas/SignedExecutionReceipt' - type: 'null' allOf: - oneOf: - properties: provider_redemption_required: const: false execution_permit: type: 'null' provider_submission_id: type: 'null' - properties: provider_redemption_required: const: true provider_submission_permitted: const: false execution_permit: $ref: '#/components/schemas/SignedExecutionPermit' provider_submission_id: $ref: '#/components/schemas/ProviderSubmissionId' - if: properties: action: const: CONSUME required: - action then: properties: execution_receipt: type: 'null' - if: properties: action: enum: - COMMIT - RELEASE - EXPIRE - SETTLE_UNKNOWN required: - action then: properties: provider_submission_permitted: const: false provider_redemption_required: const: false execution_permit: type: 'null' provider_submission_id: oneOf: - $ref: '#/components/schemas/ProviderSubmissionId' - type: 'null' execution_receipt: $ref: '#/components/schemas/SignedExecutionReceipt' - if: properties: independent_verification: const: true required: - independent_verification then: properties: action: enum: - COMMIT - RELEASE provider_evidence_id: $ref: '#/components/schemas/ProviderEvidenceId' evidence_class: enum: - FACILITATOR_SIGNED - PROVIDER_API_VERIFIED - CHAIN_FINALIZED execution_receipt: $ref: '#/components/schemas/SignedExecutionReceipt' ExecutionAuthorizationReservation: type: object additionalProperties: false required: - state - consumable - token_source - transition_uri - expires_at - processor_integration_required properties: state: $ref: '#/components/schemas/ExecutionAuthorizationState' consumable: type: boolean token_source: type: - string - 'null' enum: - signed_receipt.compact - null transition_uri: const: https://mandateshield.com/api/v2/execution-authorizations expires_at: type: - string - 'null' format: date-time processor_integration_required: const: true description: 'RESERVED means the strict ALLOW and cumulative-budget reservation committed atomically. It is not a payment instruction: an integrating processor must obtain the single winning CONSUME transition and fresh exact-bound permit claim, then use an idempotent provider request. MandateShield does not guarantee exactly-once provider delivery.' TransparencyStatus: type: object additionalProperties: false required: - status - uri properties: status: type: string enum: - RECORDED - NOT_RECORDED uri: type: string format: uri MandateBinding: type: object additionalProperties: false required: - id - version - policy_hash - source properties: id: type: string version: type: integer minimum: 1 policy_hash: type: string pattern: ^sha256:[a-f0-9]{64}$ source: const: ACCOUNT_REGISTRY responses: Unauthorized: description: API key is missing, invalid or revoked content: application/json: schema: $ref: '#/components/schemas/Error' TooLarge: description: Request exceeds the endpoint size limit content: application/json: schema: $ref: '#/components/schemas/Error' BadRequest: description: Invalid JSON, shape or parameter content: application/json: schema: $ref: '#/components/schemas/Error' LegalAcceptanceRequired: description: The authenticated live account has not accepted the current business agreements content: application/json: schema: $ref: '#/components/schemas/LegalAcceptanceRequiredError' securitySchemes: hostingSession: type: apiKey in: header name: OAI-Authenticated-User-Email description: Hosting-injected authenticated account-owner identity. The hosting boundary validates the user session and injects this assertion; callers cannot authenticate by supplying this header directly. State-changing control-plane requests additionally require the trusted same-origin check documented by the operation. bearerAuth: type: http scheme: bearer bearerFormat: ms_test_… or ms_live_… description: Keep API keys server-side and isolate them by purpose. VERIFY keys can issue challenges and strict decisions. Paid live PROCESSOR keys are bound to one processor_audience and can call only the execution-transition boundary. x-mandateshield-release: product_version: 1.13.0 openapi_version: 3.4.0 standard_version: 2.4.0 released_at: '2026-07-28T14:25:22.000Z' generated_at: '2026-07-28T14:25:22.000Z' status: current latest_pointer: https://mandateshield.com/current-release.json superseded_by: null canonical_versioned_documents: openapi: https://mandateshield.com/openapi/3.4.0.json llms: https://mandateshield.com/llms/1.13.0.txt llms_full: https://mandateshield.com/llms-full/1.13.0.txt discovery: https://mandateshield.com/discovery/1.13.0.json