Settlement provider integration

This document is the dense reference companion to the public guide Settlement with existing payment providers. It describes how Paybond sits alongside Stripe and Coinbase without replacing them, and maps the HTTP surfaces operators and integrators touch in production.

Design principles

1. Destinations are server-owned. Tenant settlement configuration in Postgres (paybond_tenant_settlement_config) is the source of truth for Connect account ids, Base USDC receive addresses, MPP profile ids, and Tempo session settings. Harbor snapshots resolved values onto each intent at create time (settlement.rs, settlementconfig/config.go).
2. Funding gates are provider-scoped. Stripe payment_intent.succeeded, Coinbase authorization events, and MPP Payment Auth verification are Harbor-internal signals. They are not substitutes for payee completion evidence.
3. Terminal settlement is evidence-driven. drive_terminal_settlement runs only from evidence_submitted, after predicate evaluation. Release vs refund is derived from the stored evaluation — not chosen by the confirm caller.
4. Tenant isolation at every hop. Gateway webhook preflight rejects events without binding metadata or with Connect destination mismatches. Internal automation routes require tenant-scoped bearer secrets or mTLS client certs with urn:paybond:tenant:<realm> URI SAN.

Three-layer architecture

sequenceDiagram
  autonumber
  actor Admin as Tenant admin
  participant GW as Gateway
  participant PG as Postgres control plane
  participant HB as Harbor
  participant PSP as Stripe / Coinbase / Tempo
  actor App as Kit / application

  Admin->>GW: Save settlement config (console or PUT /v1/admin/settlement/config)
  GW->>PG: Immutable settlement config version

  App->>GW: POST /harbor/intents (tenant API key)
  GW->>HB: Forward create (mTLS)
  HB->>PG: Read allowed rails + destination snapshot
  HB->>PSP: Initialize funding (rail-specific)
  PSP-->>HB: Authorized / pending / challenge

  PSP->>GW: Webhook (Stripe / Coinbase Hook0)
  GW->>GW: Verify signature, enqueue paybond_webhook_job
  GW->>HB: POST /internal/v1/stripe/events or /internal/v1/coinbase/events
  HB-->>HB: Fund gate, provider state hydrate

  App->>GW: POST evidence + settlement/confirm
  HB->>PSP: Capture / void / transfer / refund (terminal)
  HB-->>GW: released or refunded

Layer responsibilities

Per-rail reference

stripe_connect

• Harbor initializes a PaymentIntent against the intent-snapshotted Connect destination during create when the live Stripe runtime is enabled.
• capability_token is often available in the create response.
• drive_terminal_settlement with passed: true captures the held PI; passed: false cancels it.

stripe_ach_debit

• Shares Connect destination with card rail; requires ACH debit capability ready in settlement config.
• Intent may remain pre-funded until Stripe confirms the bank debit.
• Webhook events of interest include payment_intent.succeeded, charge.failed, mandate.updated, and dispute/refund families — see Operations runbook §2.
• Reconciliation (POST /internal/v1/stripe/reconcile) refreshes stored provider fields only; it does not mutate money.

x402_usdc_base

• Amounts are USD-denominated (cents); settlement executes in USDC on Base per session authorization.
• Gateway Coinbase webhooks use Hook0 signature verification with production timestamp tolerance 90s (configurable via PAYBOND_WEBHOOK_TIMESTAMP_TOLERANCE_SECS).
• Harbor deduplicates via durable webhook epoch + eventId + body hash (coinbase_webhook_begin_processing).
• After sled restore, operators must rotate Hook0 secrets and bump per-tenant webhook epoch — see runbook §2 x402 section.

stripe_mpp (Beta Preview)

• Funding never completes on create alone; all paths go through POST /intents/{id}/fund Payment Auth.
• Charge (intent="charge"): Stripe PI; payment_intent.succeeded webhook can complete funding if the client drops mid-handshake.
• Session (intent="session"): Tempo deposit confirmation; session_open_pending until on-chain confirm; vouchers at POST /verify meter spend under intent budget.
• Operational checklist: MPP hardening.

Post-funding terminal settlement

Harbor handler flow:

1. Payee submits evidence → POST /intents/{id}/evidence → predicate VM evaluation → evidence_submitted.
2. Caller confirms → POST /intents/{id}/settlement/confirm → drive_terminal_settlement(runtime, intent, tenant, sandbox, passed, ...).
3. Rail driver executes capture/void/transfer/refund; intent transitions to released or refunded; ledger appends terminal events.

drive_terminal_settlement returns ConflictState if the intent is not in evidence_submitted. Idempotent if already terminal.

Dispute freeze (disputed) blocks terminal settlement until Harbor dispute/resolve — see Intent lifecycle and Disputes and evidence.

HTTP surface (Gateway and Harbor)

Tenant-authenticated (public API)

Full schemas: Gateway OpenAPI, Harbor OpenAPI.

Provider webhook ingress (unsigned provider → Gateway)

Verified events enqueue in paybond_webhook_job (idempotency key = provider event id) before HTTP 2xx to the provider.

Internal automation (mTLS and/or tenant-bound bearer)

Gateway forwards webhooks using PAYBOND_HARBOR_INTERNAL_WEBHOOK_FORWARD_SECRET (with optional _PREVIOUS overlap). See Secrets and key rotation.

Stuck-intent recovery

Harbor background recovery (when env flags enabled):

• PAYBOND_HARBOR_RECOVERY_STRIPE_RECONCILE — retrieve Stripe status for non-terminal intents with stored PI ids.
• Coinbase session polling for non-terminal x402 intents with payment_session_id.
• MPP charge recovery via Stripe PI retrieve; session via Tempo deposit poll.

Recovery updates local status and safe provider fields only — no capture, transfer, or refund from reconcile alone.

Sandbox vs production

PAYBOND_SETTLEMENT_MODE=simulated is for local engineering only. Hosted sandbox uses Stripe test-mode and simulator routing per tenant environment.

Related

• Settlement with existing payment providers — adopter-facing guide
• Configure settlement rails — console setup
• Intent lifecycle — state machine
• Settlement flows — design sequences
• Operations runbook §2 — incident triage
• MPP hardening — MPP production checklist