Paybond does not replace your payment service provider (PSP). It adds intent-scoped escrow, server-owned destinations, and deterministic release or refund on top of the rails you already use.
Your Stripe Connect account, Coinbase CDP payment sessions, and Stripe Machine Payments Protocol (MPP) profile remain your provider relationships. Paybond orchestrates funding holds, evidence evaluation, and terminal money movement through Harbor while Gateway stores tenant settlement configuration and forwards provider webhooks.
Security boundary
Settlement destinations are never client-supplied. Harbor snapshots the resolved rail and destination from tenant configuration at intent create time. Client SDKs request an allowed settlement_rail; they do not pass Stripe account ids, MPP profile ids, or wallet addresses in create or fund payloads.
This guide answers what actually calls Stripe, Coinbase, or Tempo and when — after you have configured rails in the console. For rail setup, see Configure settlement rails. For create → fund → capability flows, see Fund intents by rail.
Positioning alongside your stack
| Your existing stack | What Paybond adds |
|---|---|
| Stripe Connect for card or bank debit | Intent-scoped PaymentIntent authorization, capture on release, cancel or refund on predicate failure |
| Coinbase CDP for stablecoin checkout | x402 payment-session handshake on Base; capture or void after evidence evaluation |
| Stripe MPP (Beta Preview) | Payment Auth charge or Tempo session funding; voucher metering at verify for session mode |
| Webhooks you already operate | Additional metadata-bound events (tenant_id, paybond_intent_id) consumed by Paybond for funding gates — separate from payee completion evidence |
Paybond workspace billing (subscription checkout) is unrelated to intent funding. See How intent funding works for the two-layer distinction.
Three-layer architecture
Production settlement crosses three cooperating layers:
- Admin / Gateway control plane — Tenant admins save settlement config in Configuration → Settlement. Gateway persists immutable versions in Postgres (
paybond_tenant_settlement_config) and exposesGET/PUT /v1/admin/settlement/configfor inspection and automation. - Harbor intent engine — On
POST /intents, Harbor reads the control plane, validates the requested rail against allowed rails, and snapshots the resolved destination onto the intent. Funding and terminal settlement run inside Harbor with tenant-scoped credentials. - Provider async path — Stripe and Coinbase webhooks hit Gateway (
/webhooks/stripe,/webhooks/coinbase, or environment-scoped variants). Verified events enqueue inpaybond_webhook_job, then forward to Harbor internal ingest (/internal/v1/stripe/events,/internal/v1/coinbase/events) under mTLS and bearer auth.
Typical funding path (ACH or async rails):
Principal / Kit → Gateway (auth, tenant scope) → Harbor (intent + rail)
↓
Provider (Stripe / Coinbase) ←→ Webhook → Gateway worker → Harbor internal ingest
↓
Harbor marks intent funded → capability_token minted → guarded tool spend
For the five-step settlement model (intent → escrow → evidence → evaluation → receipts), see How agent settlement works. This guide focuses on provider touchpoints in steps 2 and 5.
Per-rail integration reference
| Rail | Provider touchpoint | When funds commit | Terminal money move | Webhook / async path |
|---|---|---|---|---|
stripe_connect | Stripe PaymentIntent hold on linked Connect destination | Often during intent create when Stripe authorizes the card | Capture on release; cancel on refund | Optional PI reconcile via Harbor recovery |
stripe_ach_debit | ACH PaymentIntent on same Connect destination | After payment_intent.succeeded (bank debit confirmed) | Stripe capture / transfer on release; refund or cancel on predicate failure | Stripe → Gateway → Harbor /internal/v1/stripe/events |
x402_usdc_base | Coinbase payment session on Base | After /fund handshake and session authorization succeeds | x402 capture on release; void on refund | Coinbase Hook0 → Gateway → Harbor /internal/v1/coinbase/events |
stripe_mpp | Payment Auth charge (Stripe PI) or Tempo session deposit | /fund credential verified — charge: charge_succeeded; session: deposit_confirmed (may pass through session_open_pending) | Charge: Stripe PI capture/cancel; Session: vouchers at verify + finalize, then evidence-driven release | Charge: payment_intent.succeeded via Stripe ingest; Session: Tempo RPC recovery — see MPP hardening |
Funding signals ≠ completion evidence
Stripe payment_intent.succeeded, Coinbase authorization webhooks, and x402 session state are Harbor-internal funding gates. Payee evidence (API responses, vendor webhooks, signed receipts) is submitted after you hold a capability_token. Completion presets describe tool-completion payloads — they do not replace provider funding webhooks.
Stripe Connect (stripe_connect)
- Harbor creates or confirms a PaymentIntent against the tenant's linked Connect destination during intent create (when the runtime is live).
- Funding often completes in the same response as create; application code may read
capability_tokenimmediately. - After evidence passes, Harbor captures the held funds to the payee path configured for the intent. Predicate failure triggers cancel or refund through the same Stripe client.
ACH debit (stripe_ach_debit)
- Uses the same linked Stripe destination as card, but bank debits are delayed-confirmation.
- Create may return an intent without
capability_tokenwhile the debit is pending. - Harbor moves to
fundedonly after Stripe reports final success — typically via webhook forward, with recovery reconcile as a backstop. - Do not run paid tools or submit payee evidence until the intent is
funded.
x402 USDC on Base (x402_usdc_base)
- Harbor orchestrates Coinbase payment sessions; the tenant's Base receive address comes from settlement config only.
- Kit
fundWithX402/fund_with_x402handles the 402 challenge, payment signature, and poll until funded. - Terminal settlement calls Coinbase capture or void APIs after predicate evaluation.
Stripe MPP (stripe_mpp) — Beta Preview
- Funding is always a Payment Auth handshake on
POST /harbor/intents/{id}/fund— never on create alone. - Charge mode confirms a Stripe-backed one-shot payment; webhooks and recovery reconcile can complete funding if the client disconnects mid-handshake.
- Session mode confirms an on-chain Tempo deposit; intents may return
202withsession_open_pendinguntil Tempo confirms. - Deep dive: Fund intents on Stripe MPP.
Post-funding settlement
After the payee submits evidence and Harbor evaluates the predicate, terminal money movement runs through drive_terminal_settlement in Harbor — only from evidence_submitted state.
| Outcome | Harbor intent state | Rail behavior (summary) |
|---|---|---|
| Predicate passed | released | Capture / transfer / x402 capture / MPP charge capture per rail |
| Predicate failed | refunded | Cancel PI, ACH refund path, x402 void, or MPP refund driver |
Rail-specific capture timing:
stripe_connect— Funds were typically authorized at create; release captures the existing PaymentIntent.stripe_ach_debit— Debit already settled at funding; release drives transfer to the payee Connect destination; refund uses Stripe refund APIs on the stored charge.x402_usdc_base— Release issues a Coinbase capture against the authorized session; refund voids the authorization.stripe_mppcharge — Release captures the funded PaymentIntent; session mode still requires evidence + settlement confirm for payee payout — per-call vouchers meter spend but do not replace the terminal release step.
Application teams call POST /intents/{id}/settlement/confirm (or Kit equivalents) after evidence evaluation. Harbor derives release vs refund from the stored predicate result — callers do not choose the outcome on that route.
For the conceptual five-step model, see How agent settlement works. For state machine detail, see Intent lifecycle.
Operational scenarios (FAQ)
Intent stuck unfunded
| Symptom | Likely rail | What to check |
|---|---|---|
No capability_token after create | stripe_ach_debit | Stripe PaymentIntent still processing; webhook delivery in Stripe Dashboard |
/fund returns 402 repeatedly | x402_usdc_base or stripe_mpp | Client credential missing or expired; challenge TTL (MPP default 15m) |
/fund returns 202, session_open_pending | stripe_mpp session | Tempo deposit not confirmed; PAYBOND_TEMPO_RPC_URL on Harbor; recovery worker |
Intent open / pre-funded in console | Any live rail | Provider dashboard vs Harbor settlement_provider fields |
Response principles:
- Do not patch Harbor rows to fake
funded— preserve provider ids (payment_intent_id,payment_session_id, MPP challenge ids) and retry canonical/fundor let recovery converge. - ACH: never mark funded while Stripe reports pending bank-debit state.
- x402: confirm Gateway received the Coinbase webhook on
/webhooks/coinbasebefore forcing manual recovery.
Webhook delivery failure
Gateway verifies signatures, enqueues jobs with provider event idempotency keys, and forwards to Harbor once per event.
Operator entry points:
- Console: Settlements webhook health (
GET /v1/stripe/webhook-health) for Stripe delivery and processing status. - Internal (break-glass):
POST /internal/v1/stripe/reconcilewith tenant-scoped bearer fromPAYBOND_STRIPE_RECONCILIATION_SECRETS— read-only provider state refresh; does not create transfers or refunds. - Harbor recovery ticks:
PAYBOND_HARBOR_RECOVERY_STRIPE_RECONCILEand Coinbase session polling when enabled — heals drift after outages.
Events missing metadata.tenant_id or metadata.paybond_intent_id are stored for manual review and are not forwarded to Harbor. Ensure your Stripe PaymentIntents include Paybond metadata at funding time.
Full triage steps: Operations runbook §2.
Sandbox vs production
| Environment | Provider behavior |
|---|---|
| Sandbox tenant | Simulator routing — no live Stripe or Coinbase money movement; paybond.guardrails.bootstrapSandbox for fastest funded intent |
| Production | Live Connect destination, Coinbase CDP token, MPP secrets, and webhook endpoints required per Configure settlement rails checklist |
Sandbox ACH uses Paybond simulator routing without a Stripe test secret. Hosted sandbox stripe_mpp can use Stripe test-mode when Harbor has PAYBOND_STRIPE_MPP_TEST_SECRET_KEY and the tenant configures profile_test_*.
Tenant isolation reminder
Every Gateway and Harbor call must carry tenant scope from authenticated credentials (service-account API key, operator session, or internal automation secret bound to a tenant). Webhook forwards validate metadata and Connect destination inventory before Harbor ingest. Cross-tenant destination mismatch is rejected at the Gateway preflight.