Start self-serve, then carry one evidence shape across supported outcomes.

STEP 1 · CHALLENGE

Bind signing to this attempt

const challenge = await client.createChallenge({
  mandate_id: purchase.mandate_id,
  protocol: purchase.protocol,
  key_thumbprint: process.env.MANDATESHIELD_KEY_THUMBPRINT
})

// The pinned authority issuer signs:
// challenge.issuer + challenge.audience + challenge.nonce + iat + exp
// + the SHA-256 digest of the exact final envelope.
const evidence = await authorityIssuer.sign(purchase, challenge)

STEP 2 · VERIFY + RESERVE

Require the full invariant; do not submit

const reservation = requireAllowed(await verifier.verifyAuthority({
  envelope: purchase,
  evidence
}))

// RESERVED authority is not provider-submission authority.
const base = {
  receipt_id: reservation.signed_receipt.receipt_id,
  compact: reservation.signed_receipt.compact,
  expected_envelope: purchase,
  expected_audience: challenge.audience
}

STEP 3 · CONSUME + ISSUE

Bind one exact provider request

Every account created at or after 2026-07-26T12:01:24.000Z must include an exact provider_binding on CONSUME. Only older accounts retain legacy unbound compatibility; new integrations must never depend on it. Provider-bound CONSUME moves the reservation to CONSUMED and creates a prepared durable submission plus an ES256 permit valid for at most 60 seconds. It deliberately returns provider submission permission false; the customer, agent and merchant cannot use this response to call the provider.

const consumed = await post(
  "/api/v2/execution-authorizations",
  process.env.MANDATESHIELD_PROCESSOR_KEY,
  {
  ...base,
  action: "CONSUME",
  idempotency_key: `${purchase.idempotency_key}:consume`,
  provider_binding: {
    profile: "STRIPE_PAYMENT_INTENTS_V1",
    environment: "live",
    account: purchase.payee_identity.binding.merchant_account_id,
    request_id: providerRequestId,
    payee_destination:
      purchase.payee_identity.binding.connected_account_id,
    method: "POST",
    resource: "https://api.stripe.com/v1/payment_intents",
    body_digest: providerBodyDigest
  }
})

if (
  consumed.provider_submission_permitted !== false ||
  consumed.provider_redemption_required !== true ||
  !consumed.execution_permit?.compact
) {
  throw new Error("Provider-bound permit was not issued")
}

STEP 4 · REDEEM + SUBMIT

Grant one fresh MandateShield claim at the execution edge

Atomic online redemption claims the prepared submission and grants one fresh permission in MandateShield's own state. The customer-deployed exclusive executor proceeds only when that single-winner claim returns true and must attempt the exact provider operation idempotently using the key carried in the signed permit and returned by redemption. MandateShield does not guarantee exactly-once provider delivery. Signature-only verification reports online state unknown and never grants submission.

// Run only in a customer-deployed exclusive executor.
const inspected = await postPublic(
  "/api/v2/execution-permits/verify",
  {
    compact: consumed.execution_permit.compact,
    expected_audience: challenge.audience
  }
)
if (inspected.provider_submission_permitted !== false) {
  throw new Error("Offline/signature verification must never grant")
}

const redeemed = await post(
  "/api/v2/execution-permits/redeem",
  process.env.MANDATESHIELD_PROVIDER_PROCESSOR_KEY,
  {
    compact: consumed.execution_permit.compact,
    idempotency_key: `${purchase.idempotency_key}:redeem`,
    expected_request: {
      provider: inspected.claims.provider,
      payee: inspected.claims.payee,
      amount: inspected.claims.amount,
      resource: inspected.claims.resource
    }
  }
)
if (
  redeemed.provider_submission_permitted !== true ||
  redeemed.status !== "CLAIMED" ||
  redeemed.idempotent_replay !== false
) throw new Error("No fresh redemption")

// The MandateShield claim is single-winner; provider delivery is not exactly-once.
const outcome = await submitIdempotentlyToProvider(purchase, {
  idempotencyKey: redeemed.provider_idempotency_key
})

STEP 5 · TERMINAL RECEIPT

Report a hint; let MandateShield check the native evidence

Report the exact submission, permit, claim, provider reference and bounded caller outcome to the hosted reconciliation endpoint. That report is stored as CALLER_ASSERTED evidence and does not finalize the authorization by itself. MandateShield then checks the configured Stripe API or x402 chain without trusting that caller report. Exact, non-conflicting PROVIDER_API_VERIFIED or CHAIN_FINALIZED evidence can autonomously COMMIT or RELEASE and return a signed terminal execution receipt with independent_verification=true. Pending, unknown or conflicting outcomes remain fail-closed for reconciliation.

Direct manual COMMIT or RELEASE remains supported. Its processor_result is authenticated by the PROCESSOR key and exact audience binding, but the receipt remains CALLER_ASSERTED with independent_verification=false. Always inspect the evidence class and independent-verification flag after verifying the ES256 signature.

const report = await post(
  "/api/v2/provider-submissions",
  process.env.MANDATESHIELD_PROVIDER_PROCESSOR_KEY,
  {
    provider_submission_id: redeemed.provider_submission_id,
    permit_id: redeemed.permit_id,
    claim_id: redeemed.claim_id,
    payment_reference: outcome.reference,
    outcome: outcome.status,
    occurred_at: outcome.occurredAt,
    provider_observation: outcome.boundedObservation
  }
)

if (
  report.terminal_transition_permitted !== true ||
  report.independent_verification !== true ||
  !["PROVIDER_API_VERIFIED", "CHAIN_FINALIZED"].includes(
    report.evidence_class
  ) ||
  report.authorization_finalized !== true ||
  !report.execution_receipt?.compact
) {
  await queueProviderReconciliation(redeemed.provider_submission_id)
  throw new Error("Provider outcome remains fail-closed")
}