Fund intents on Stripe MPP

In short: this is the funding path for one specific rail (Stripe MPP), so an agent's usage-metered spend can move machine-to-machine over HTTP. stripe_mpp is Paybond's Machine Payments Protocol settlement rail. Harbor advances funding on POST /harbor/intents/{id}/fund with HTTP Payment Auth semantics — 402 challenges, app-owned credentials, and Payment-Receipt on success.

This guide is the deep dive for stripe_mpp only. For the full multi-rail create → fund → capability flow, see Fund intents by rail. For tenant-admin rail setup, see Configure settlement rails.

Charge vs session — which helper?

MPP exposes two funding modes on the same rail literal. Pick the Kit helper that matches your spend shape — the helper selects the correct WWW-Authenticate: Payment … challenge.

Charge maps to a Stripe-backed one-shot authorization (PaymentIntent / SPT-style credential). Paybond verifies the credential, confirms the charge, then mints capability_token.

Session opens a Tempo payment channel: one Paybond intent maps to one channel. Paybond verifies the open-session credential, confirms the on-chain reserve deposit (Tempo testnet in sandbox, mainnet in production), opens the channel, then mints capability_token. Subsequent tool spend consumes cumulative vouchers under the existing Paybond guardrail lifecycle — vouchers do not move the intent to released; evidence and settlement confirmation still gate payee payout.

Decision guide

For protocol background and status mapping, see the stripe_mpp support matrix row and MPP Payment Auth handshake.

Payment Auth header flow

Paybond never marks an MPP intent funded on create alone. Funding is a two-step (or poll) handshake on the same route.

Step-by-step

Gateway vs Harbor path

Gateway translates x-paybond-payment-authorization → Authorization: Payment when forwarding. Response headers (WWW-Authenticate, Payment-Receipt, Cache-Control, x402-compat payment-required / payment-response) pass through unchanged.

Invalid credentials

When a credential is rejected, expect:

• 402 Payment Required
• Content-Type: application/problem+json (RFC 9457 problem details)
• Fresh WWW-Authenticate challenge(s)
• Cache-Control: no-store

Fix the credential and retry with a new challenge — do not treat a 402 with a problem body as funded. Reuse the same idempotency-key and empty JSON body {} on safe retries.

Session deposit pending (202 Accepted)

Tempo session funding may return 202 Accepted when the open transaction is broadcast but the on-chain reserve deposit is not confirmed yet:

• state remains open
• funding.status = session_open_pending
• funding.channel_id and last_settle_tx_hash are available for support debugging
• Kit helpers poll /fund until capability_token is present or a terminal failure surfaces (PaybondMppFundingPendingError when polling exhausts)

Paybond also reconciles pending session opens in the background and mints the capability token when the deposit confirms. Poll with fresh recognition proofs; you do not need to resubmit the Payment Auth credential on each poll once the open credential was accepted.

Recognition proofs

Each /fund call needs a fresh AgentRecognitionProofV1 with purpose: "harbor.intent.fund" bound to the tenant and request envelope. Kit helpers issue proofs through your issueRecognitionProof callback. Proof nonces are single-use — credential retries need their own recognition proof.

Sandbox behavior

In sandbox, MPP funding runs against Stripe test mode — the same Payment Auth flow as production, without live money. Before you fund, paste your Stripe test MPP profile id (profile_test_...) in Configuration → Settlement and enable the stripe_mpp rail.

Dual challenges. When Tempo session funding is enabled and a recipient is configured, the first charge-mode /fund without a credential may return both charge and session WWW-Authenticate values. Kit selects automatically:

• fundWithMppCharge → intent="charge", method="stripe"
• fundWithMppSession → intent="session", method="tempo"

For the fastest sandbox path without writing MPP wallet code, use paybond.guardrails.bootstrapSandbox(...) to get a pre-funded intent — see One-command guardrails.

Offline Kit tests can use paybond dev loop --offline; end-to-end Stripe test-mode MPP and Tempo testnet checks are opt-in.

Kit integration

One-shot charge (TypeScript)

const created = await paybond.intents.create({
  operation: "saas.api.purchase",
  requestedSpendCents: 5_000,
  currency: "usd",
  settlementRail: "stripe_mpp",
  completionPreset: "api_response_ok",
});

const funded = await paybond.intents.fundWithMppCharge({
  intentId: created.intent_id,
  recognitionProof: await issueAgentRecognitionProofV1({
    purpose: "harbor.intent.fund",
    method: "POST",
    path: `/harbor/intents/${created.intent_id}/fund`,
    body: {},
  }),
  createPaymentCredential: (challenge) => mppWallet.createPaymentCredential(challenge),
  issueRecognitionProof: (envelope) =>
    issueAgentRecognitionProofV1({
      purpose: "harbor.intent.fund",
      method: envelope.method,
      path: envelope.path,
      body: envelope.body,
    }),
});

const capabilityToken = funded.capabilityToken;

Tempo session channel (Python)

funded = await paybond.intents.fund_with_mpp_session(
    intent_id=intent_id,
    recognition_proof=fund_recognition_proof,
    create_payment_credential=mpp_wallet.create_payment_credential,
    issue_recognition_proof=issue_fund_recognition_proof,
)
capability_token = funded.capability_token

Prefer these helpers over manual /fund loops — they parse challenges, invoke your credential callback, set paymentAuthorization, poll pending states, and stop on terminal failures (PaybondMppFundingFailedError / PaybondMppFundingPendingError in TypeScript).

Funding response fields

After challenges progress, inspect funding on the fund result:

See SDK reference — IntentFundingResult and Harbor MPP handshake.

Session voucher metering at verify

After session funding, the intent stays funded while the agent runs metered tool calls. Harbor does not advance the intent to released on each voucher — terminal payout still requires evidence submission and settlement confirmation.

For stripe_mpp session intents, POST /harbor/verify (Gateway POST /verify) performs capability checks and accepts a Tempo voucher credential when metering spend inside the open channel.

Verify handshake (session intents only)

Charge-mode MPP intents skip the voucher path — capability verification alone is sufficient after one-shot funding.

Budget cap and cumulative vouchers

Paybond enforces the signed intent budget (amount_cents, converted to USDC base units as amount_cents × 10 000) at voucher acceptance time:

• Each voucher carries a monotonic cumulative spend total for the Tempo channel.
• Vouchers whose cumulative total exceeds the intent budget are rejected, even when the session deposit ceiling is higher.
• Only one pending voucher may be in flight per intent. Complete gateway spend finalization (commit or release) before submitting the next voucher credential.
• Rejected vouchers do not advance accepted_cumulative_base_units or set pending_cumulative_base_units.

Inspect funding.accepted_cumulative_base_units and funding.pending_cumulative_base_units on verify responses and intent detail for metering state. Kit spend guards still enforce per-operation requested_spend_cents against the capability token — vouchers meter Tempo spend under the same intent ceiling.

Challenge binding on fund and verify

MPP challenges include:

Empty-body fund requests use the digest of an empty string. Verify requests use the JCS-canonical JSON body on POST /verify.

Tenant isolation — critical boundaries

MPP funding touches payment credentials and channel state. Treat cross-tenant access as a severity-zero defect.

Cross-tenant fund or voucher attempts are rejected. Stale or replayed challenge_id and voucher credentials fail without changing intent state. Vouchers that would exceed the intent amount_cents budget are rejected.

Integration checklist

Tenant admin (before first MPP fund)

• Paid plan activated (production) or sandbox workspace selected
• Stripe Connect destination linked (MPP routes through your linked Stripe destination)
• In Configuration → Settlement, paste your MPP profile id (profile_test_... in sandbox, profile_... in production) and confirm readiness shows the profile as configured
• For session mode: set a Tempo recipient and enable Tempo session funding in Settlement settings
• stripe_mpp added to allowed rails

Application developer

• settlementRail: "stripe_mpp" / settlement_rail: "stripe_mpp" with currency: "usd"
• Chose charge or session helper before first /fund
• App-owned createPaymentCredential / create_payment_credential wired
• Fresh recognition proof per /fund attempt
• Guard tools only after capability_token is present
• For session mode: wire voucher credentials on POST /verify (via spend guard) and respect single pending voucher semantics
• Submit tool-completion evidence after guarded work — not Payment Auth receipts or Stripe PaymentIntent ids

Common mistakes

• Using fundWithMppCharge when you need streaming vouchers — switch to fundWithMppSession at create time.
• Sending Authorization: Payment through Gateway — use x-paybond-payment-authorization so Bearer auth still works.
• Treating 402 with application/problem+json as success — only 200 with a capability_token means funded; 202 with session_open_pending means keep polling.
• Submitting a second voucher while one is pending — wait for spend completion finalize (commit/release) before the next verify credential.
• Assuming deposit size overrides intent budget — cumulative vouchers are capped at signed amount_cents, not merely the Tempo channel deposit.
• Submitting funding payloads as completion evidence — the completion rule evaluates vendor tool results, not MPP challenge ids.
• EUR or multi-currency intents on stripe_mpp — rejected at create until policy expands.

Where to go next