Harbor is Paybond's outcome-verified escrow and settlement API. Use it to create intents, collect evidence, release or refund funds, manage disputes, and export tenant-scoped proof of what happened.
- Base path: Paybond exposes selected Harbor routes through the Gateway under the
/harborprefix. For example,GET /harbor/operator/v1/summarymaps to Harbor'sGET /operator/v1/summary. Raw Harbor ledger event pages remain protected Harbor upstream routes; customer-facing ledger verification is exposed by Gateway under/v1/compliance/ledger/*. - Authentication: Send a Bearer token in
Authorization. Kit SDKs open Harbor sessions for you; direct integrations can mint a Harbor access token through Authentication. - What Harbor guarantees: tenant-scoped access, retry-safe writes on supported routes, server-owned settlement routing, and signed provenance for each state transition.
Route map
Intents
Use these routes to create an intent, collect funding and evidence, confirm the payout decision, or verify a capability token against an existing intent.
| Method | Path | Description |
|---|---|---|
POST | /intents | Create a signed intent with the budget, participants, and payout rules for the transaction. |
POST | /intents/{intent_id}/fund | Advance delayed funding flows for an existing intent. x402_usdc_base and stripe_ach_debit return rail-specific funding instructions; ACH debit intents remain open until final bank-debit confirmation. Stripe Connect funding is initialized during intent creation where enabled. |
POST | /intents/{intent_id}/evidence | Submit evidence and receive a structured evaluation result. |
POST | /intents/{intent_id}/settlement/confirm | Confirm the settlement action derived from the recorded evidence evaluation. A passing predicate releases; a failing predicate refunds/cancels. |
POST | /verify | Verify a Paybond capability token against the target intent. |
POST /intents, POST /intents/{id}/fund, POST /intents/{id}/evidence, and POST /intents/{id}/settlement/confirm accept an optional idempotency-key header so safe retries do not create duplicate transitions. For the shared retry contract, see Errors.
Predicate documents must follow the supported Harbor predicate rules reference.
Settlement destinations are configured and resolved by Paybond. Create-intent callers must request and principal-sign a settlement_rail (stripe_connect, stripe_ach_debit, or x402_usdc_base), but Harbor chooses the effective destination from the tenant's approved settlement configuration and reuses that routing across funding, confirmation, and dispute flows. ACH debit is a delayed-confirmation rail: Harbor keeps the intent open while funding is pending and marks it funded only after Paybond receives final rail confirmation.
In sandbox tenant context, stripe_ach_debit uses Paybond's simulator destination and sandbox lifecycle events, so tenant admins can test ACH routing from the hosted console without real Stripe test-mode credentials. Real Stripe ACH test-mode execution is an opt-in engineering/operations check, not a prerequisite for tenant sandbox onboarding.
For stripe_ach_debit, POST /intents/{intent_id}/fund also returns mandate_context so UIs can show the Stripe-hosted mandate posture before confirmation: Payment Element, platform merchant-of-record, the PAYBOND ACH statement descriptor, the amount/currency, separate charge and transfer funds flow, and the rule that ACH processing is not funded.
Rail-specific provider references in funding or operator responses are opaque support fields. Application lifecycle logic should use Harbor's state, funded, and terminal outcome fields rather than branching on provider-specific ids or statuses.
Operator workflows
These routes power the Paybond operator experience for the authenticated tenant, including search, review, and dispute handling.
| Method | Path | Description |
|---|---|---|
GET | /operator/v1/summary | Tenant-scoped summary counts and settlement totals. |
GET | /operator/v1/usage | Tenant-scoped current-cycle runtime counters, plan caps, and overage projection used for billing and readiness checks. This is an operator surface, not a settlement workflow. |
GET | /operator/v1/intents | Paginated intent list with filters such as status, operator, and time window. |
GET | /operator/v1/intents/{id} | One intent with its timeline, evidence, and settlement state. |
POST | /operator/v1/intents/{id}/protocol/mandate-bind | Bind a verified signed AgentMandateV1 digest to an intent exactly once. |
POST | /operator/v1/intents/{id}/dispute/open | Move a funded or evidence-submitted Harbor intent into dispute review and return the updated intent state. Gateway dispute case routes create and manage case_id records. |
POST | /operator/v1/intents/{id}/dispute/resolve | Resolve a Harbor dispute through the configured rail with action=release or action=refund. Gateway dispute cases can separately record split or external-escalation case statuses. |
The summary, list, detail, protocol-bind, usage, and dispute routes are exposed through /harbor/operator/v1/* and are limited to the authenticated tenant and operator permissions. The protocol mandate bind route records the verified mandate subject and digest exactly once for the target intent.
Ledger
These protected Harbor routes expose signed history and verifier packs for trusted ingestion and proof checks. Gateway exposes customer-facing continuity checks and verifier-pack workflows under /v1/compliance/ledger/*; it does not expose the raw paginated event route under /harbor/ledger/v1/events.
| Method | Path | Description |
|---|---|---|
GET | /ledger/v1/tip | Current tip: sequence and entry commitment; empty when the tenant ledger has no rows yet. |
GET | /ledger/v1/authority | Hex-encoded Ed25519 verifying key for this Harbor deployment (offline signature checks). |
GET | /ledger/v1/events | Tenant-scoped append-only page. Query: after_seq (exclusive cursor, default 0), limit (1–256, default 64). |
GET | /ledger/v1/merkle/latest | Latest completed Merkle batch checkpoint JSON (checkpoint may be null); includes deterministic signature fields when Harbor can derive the signed checkpoint envelope. |
GET | /ledger/v1/verify | Tenant-scoped continuity verification result: signed row chain, closed-batch checkpoint coverage, and actionable failure guidance. |
GET | /ledger/v1/verifier-pack | Export the tenant’s self-contained continuity proof pack: signed ledger rows, signed checkpoints, witness freshness metadata, checkpoint-lineage witnesses, and observed signing-key epochs for offline reruns. |
POST | /ledger/v1/verifier-pack/verify | Re-verify an exported verifier pack without direct sled access. Fails closed on stale witness material, checkpoint witness drift, or key-transparency mismatches and returns the same verified/failed guidance contract as /ledger/v1/verify. |
Use the verifier-pack and verification endpoints when a customer, partner, or compliance workflow needs to confirm ledger continuity or export portable proof material. Use GET /ledger/v1/events for trusted ingestion and operator automation, not as a public customer event feed. For the product guarantees behind these routes, see Ledger and provenance.
Policy registry
Use the policy registry to preview, test, publish, and roll back versioned payout rules without changing application code.
| Method | Path | Summary |
|---|---|---|
GET | /policy/v1/templates | List global policy template catalog (read-only, no tenant state). |
POST | /policy/v1/preview | Materialize DSL and human summary from { template_id, parameters } without persisting. |
POST | /policy/v1/test | Evaluate sample evidence against a materialized template (sandbox harness). |
GET | /policy/v1/versions?template_id=… | List tenant versions for one template. |
POST | /policy/v1/versions | Create a draft from { template_id, parameters }. |
GET | /policy/v1/versions/{template_id}/{seq} | Fetch one version row (state, materialized_dsl, content_digest_hex). |
POST | /policy/v1/versions/{template_id}/{seq}/publish | Publish an approved draft; updates tenant head for new intents. |
POST | /policy/v1/versions/{template_id}/{seq}/deprecate | Deprecate a version (must not be current head). |
POST | /policy/v1/versions/{template_id}/{seq}/retire | Retire a deprecated version. |
POST | /policy/v1/rollback | Move published head to a prior approved version. Customer-facing Gateway calls require explicit current-head, target-digest, reason, and confirm=true preconditions before Harbor receives the request; Gateway returns 428 for missing fields, 400 for a missing/short reason, and 409 for stale head or digest mismatch. Gateway writes redacted rollback rejection/request audit events before forwarding, returns 503 if that pre-forward audit sink is unavailable, and writes the post-Harbor outcome audit best effort. |
Preview and test routes help teams validate rule changes before publish. Published versions become the default policy head for new intents; changing the head does not rewrite historical intents.
When policy lifecycle routes are called through Gateway (/harbor/policy/v1/*), Gateway first applies the tenant guardrail policy. enforce mode blocks disallowed templates before Harbor receives the request; observe mode forwards the request and records a redacted observed_violation audit event.
Access rules:
- Read (
GET …/templates,GET …/versions,GET …/versions/{…}) — operator or tenant admin. - Sandbox (
POST …/preview,POST …/test) — operator or tenant admin. - Lifecycle mutations (
POST …/versions,POST …/rollback, publish/deprecate/retire) —tenant.adminentitlement only.
Tenant isolation
Every Harbor read and write is scoped to the authenticated tenant realm. Harbor refuses to:
- Bind evidence from intent A to intent B across tenants.
- Redeem a capability token whose
tenant_idclaim differs from the session. - Append to the ledger without a signed tenant envelope.
See Tenant model for the full platform boundary.