openapi: 3.2.0 info: title: MandateShield Payment Authority Protocol adapters 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: Protocol adapters description: Stateless documented-field projection for supported agent-payment inputs. X402 and MPP require a canonical payee identity whose rail-specific fields exactly match the source. A successful projection is not full source-protocol conformance or independent trust-evidence verification; output is deliberately non-executable and must pass strict authority verification before use. paths: /api/v2/normalize: post: operationId: normalizeAgentPaymentProtocol tags: - Protocol adapters summary: Project AP2, x402 v2, or MPP payment fields description: Maps one documented source projection into the deterministic MandateShield purchase envelope. X402 requires exact network+payTo identity plus a trusted merchant-mapping evidence reference; MPP requires exact HTTPS service origin+method identity. projection_fields_valid=true means only that supported fields and explicit mappings passed. The endpoint does not fetch or independently verify the evidence reference, establish full source-protocol conformance, or verify source signature, issuer trust, delegated authority, payment credential, or settlement; it always returns enforcement_authorized=false. Strict v2 verification remains mandatory. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - adapter - source - context properties: adapter: type: string enum: - AP2_CLOSED_PAYMENT_SD_JWT - X402_V2_PAYMENT_REQUIRED - MPP_HTTP_PAYMENT_CHALLENGE source: description: 'Raw protocol input: AP2 compact SD-JWT, x402 PAYMENT-REQUIRED base64 JSON, MPP WWW-Authenticate Payment challenge, or the documented decoded object.' context: type: object additionalProperties: false required: - mandate_id - agent_id properties: mandate_id: type: string minLength: 1 maxLength: 240 agent_id: type: string minLength: 1 maxLength: 240 idempotency_key: type: string minLength: 1 maxLength: 256 created_at: type: string format: date-time merchant_id: type: string minLength: 1 maxLength: 240 resource: type: string minLength: 1 maxLength: 2048 asset_id: type: string minLength: 1 maxLength: 500 asset_decimals: type: integer minimum: 0 maximum: 30 user_consent: type: boolean amount_unit: type: string enum: - MINOR_UNITS - ATOMIC_UNITS mpp_request_profile: type: string enum: - MANDATESHIELD_PORTABLE_CHARGE_V1 description: Required for MPP because the core protocol delegates request field semantics to method-specific specifications. x402_execution_profile: type: string enum: - MANDATESHIELD_X402_V2_EXACT_EIP3009_V1 description: Opt-in strict first-party x402 execution binding. Requires method and exact request digests. http_method: type: string enum: - GET - HEAD - POST - PUT - PATCH - DELETE http_body_sha256: type: string pattern: ^sha256:[a-f0-9]{64}$ http_headers_sha256: type: string pattern: ^sha256:[a-f0-9]{64}$ 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. selection: type: object additionalProperties: false properties: index: type: integer minimum: 0 maximum: 24 responses: '200': description: Syntax normalized into a non-executable purchase envelope content: application/json: schema: $ref: '#/components/schemas/ProtocolAdapterResult' '400': $ref: '#/components/responses/BadRequest' '413': $ref: '#/components/responses/TooLarge' components: schemas: Error: type: object required: - error properties: error: type: string code: type: string enforcement_authorized: type: boolean ProtocolAdapterResult: type: object additionalProperties: false required: - adapter - adapter_version - protocol - source_digest - envelope_digest - envelope - bindings - assurance - next_step - warnings properties: adapter: type: string enum: - AP2_CLOSED_PAYMENT_SD_JWT - X402_V2_PAYMENT_REQUIRED - MPP_HTTP_PAYMENT_CHALLENGE adapter_version: const: 1.0.0 protocol: type: string enum: - AP2 - X402 - MPP source_digest: type: string pattern: ^sha256:[a-f0-9]{64}$ envelope_digest: type: string pattern: ^sha256:[a-f0-9]{64}$ envelope: $ref: '#/components/schemas/PurchaseEnvelope' bindings: type: object additionalProperties: true assurance: type: object additionalProperties: false required: - projection_fields_valid - source_signature_verified - source_trust_verified - delegated_authority_verified - payment_credential_verified - settlement_verified - enforcement_authorized properties: projection_fields_valid: const: true description: The fields used by the documented MandateShield projection passed adapter validation. This is not full source-protocol conformance. source_signature_verified: const: false source_trust_verified: const: false delegated_authority_verified: const: false payment_credential_verified: const: false settlement_verified: const: false enforcement_authorized: const: false next_step: type: string warnings: type: array items: type: string 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 responses: 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' 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