Fund intents on Stripe MPP

Beta Preview. 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). Harbor verifies the credential, confirms the charge, then mints capability_token.

Session opens a Tempo v2 payment channel: one Paybond intent maps to one channel. Harbor verifies the open-session credential, confirms the TIP-1034 reserve deposit on-chain when PAYBOND_TEMPO_RPC_URL is configured (sandbox Moderato or production mainnet), 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 Harbor state mapping, see MPP rail evaluation.

Payment Auth header flow

Harbor 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 direct Harbor

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

Invalid credentials

When Harbor rejects a credential, 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 402 + problem body as funded. Reuse the same idempotency-key and empty JSON body {} on safe retries.

Session deposit pending (202 Accepted)

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

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

Harbor's background recovery worker also reconciles session_open_pending intents by re-querying the Tempo RPC and minting 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 Harbor has accepted the open credential.

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

Hosted sandbox tenants rehearse real Stripe test-mode MPP when Harbor has PAYBOND_STRIPE_MPP_TEST_SECRET_KEY configured. Tenants self-configure a profile_test_* Stripe MPP profile id in Settlement settings before funding.

Dual challenges. When mpp_session_enabled is true and a Tempo 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"

Harbor's simulated MPP runtime (PAYBOND_SETTLEMENT_MODE=simulated) is for local unit tests only — not the default hosted sandbox path.

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 and WireMock mappings; live Stripe sandbox MPP and Tempo testnet checks run only behind explicit env flags — never in default make all.

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

Harbor 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.
• Harbor rejects vouchers whose cumulative total exceeds the intent budget, 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 rail-internal Tempo spend under the same intent ceiling.

Challenge binding on fund and verify

MPP challenges issued by Harbor include:

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

Tenant isolation — critical boundaries

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

Harbor security tests enforce: tenant A cannot fund or voucher tenant B's intent or channel; stale or replayed challenge_id and voucher credentials fail without state mutation; vouchers that would exceed the intent amount_cents budget are rejected without pending state.

MPP lifecycle events (challenge_consumed, charge_succeeded, session_opened, voucher pending/commit/release, finalize applied/skipped) are recorded as mpp_provider_event ledger rows for Signal fraud review.

Integration checklist

Tenant admin (before first MPP fund)

• Paid plan activated (production) or sandbox tenant selected (rehearsal)
• Stripe Connect destination linked (MPP routes through the tenant's linked Stripe destination)
• In Configuration → Settlement, MPP profile configured — paste stripe_mpp_profile_id; readiness shows stripe_mpp_profile_configured
• For session mode: set Tempo recipient and enable Tempo session funding in Settlement settings (mpp_tempo_recipient_address, mpp_session_enabled)
• Production Harbor has PAYBOND_TEMPO_RPC_URL when live tenants allow stripe_mpp session funding
• Hosted sandbox Harbor has PAYBOND_STRIPE_MPP_TEST_SECRET_KEY when sandbox tenants allow stripe_mpp
• 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 + problem+json as success — only 200 + capability_token means funded; 202 + 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 — predicates evaluate 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