Settlement with existing payment providers

In short: your existing Stripe or Coinbase setup still moves the money — Paybond decides when it's allowed to move. 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.

For how Paybond complements Stripe Agentic Commerce Suite, ACP, and UCP (checkout execution vs conditional settlement), see Paybond with Stripe agentic commerce.

For Shopify UCP/MCP checkout tools and binding metadata, see Protect Shopify payments from agents and Configure Shopify settlement.

For BYO Adyen Checkout manual capture, see Configure Adyen settlement. For BYO Flutterwave Virtual Account settlement across African corridors (NGN, GHS), see Configure Flutterwave settlement. For self-serve BYO Paystack Dedicated Virtual Account settlement in NGN (paystack_nip), see Configure Paystack settlement. For Plaid Auth as bank verification under stripe_ach_debit, see Configure Plaid bank verification.

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 — and stores settlement configuration and provider webhook delivery for your workspace.

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

Paybond workspace billing (subscription checkout) is unrelated to intent funding. See How intent funding works for the two-layer distinction.

How the pieces fit together

Production settlement has three customer-visible layers:

1. Settlement configuration — Tenant admins save rails and destinations in Configuration → Settlement. The same state is available via GET / PUT /v1/admin/settlement/config for automation.
2. Intent funding and settlement — On create, Paybond validates the requested rail against allowed rails and snapshots the resolved destination onto the intent. Funding and terminal release/refund use your tenant-scoped credentials.
3. Provider webhooks — Stripe, Coinbase, and other providers notify Paybond at the public webhook endpoints for your environment. Verified events advance funding and terminal settlement for the matching intent.

Typical funding path (ACH or async rails):

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

Stripe Connect (stripe_connect)

• Paybond 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_token immediately.
• After evidence passes, Paybond 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_token while the debit is pending.
• The intent moves to funded only after Stripe reports final success — typically via webhook, with automatic 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)

• Paybond orchestrates Coinbase payment sessions; the tenant's Base receive address comes from settlement config only.
• Kit fundWithX402 / fund_with_x402 handles the 402 challenge, payment signature, and poll until funded.
• Terminal settlement calls Coinbase capture or void APIs after the completion rule is evaluated.

Stripe MPP (stripe_mpp)

• 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 automatic reconcile can complete funding if the client disconnects mid-handshake.
• Session mode confirms an on-chain Tempo deposit; intents may return 202 with session_open_pending until Tempo confirms.
• Deep dive: Fund intents on Stripe MPP.

Adyen manual capture (adyen_manual_capture)

• Tenant admins save merchant account, API key, and HMAC secret in Configure Adyen settlement.
• Paybond places a manual-capture authorization at create (simulated under sandbox).
• Terminal capture/cancel stays pending until Adyen webhooks confirm — do not treat the capture/cancel API response alone as Released/Refunded.
• HMAC: A vaulted destination HMAC secret is required; live Adyen webhooks with a missing or invalid signature are rejected.
• Chargebacks: Bound CHARGEBACK notifications (tenant / intent / payment reference) freeze disputable intents for operator resolution; unbound stays observation / manual review. See Disputes and evidence evaluation.
• Recovery: When capture/cancel webhooks lag, Paybond reconciles pending modifications against Adyen.
• CLI: after paybond login, run paybond adyen ready or paybond adyen doctor to verify rail/destination/HMAC readiness (no secret upsert via CLI).
• Setup walkthrough: Configure Adyen settlement.

Flutterwave virtual account (flutterwave_virtual_account)

• Tenant admins save secret key and webhook secret in Configure Flutterwave settlement. V1 corridors: NGN and GHS.
• Paybond provisions or displays VA funding instructions at create; funding completes when a verified VA credit webhook confirms the bank transfer.
• Terminal Transfer payout or refund/reversal stays pending until Flutterwave webhooks confirm — do not treat the Transfer API response alone as Released/Refunded.
• Webhook verify: Paybond verifies Flutterwave signature headers; missing or invalid signatures are rejected and never fund an intent.
• Recovery: When transfer/refund webhooks lag, Paybond reconciles pending terminal state against Flutterwave transfer status.
• CLI: after paybond login, run paybond flutterwave ready or paybond flutterwave doctor to verify rail/destination/webhook-secret readiness (no secret upsert via CLI).
• Setup walkthrough: Configure Flutterwave settlement.

Paystack NIP (paystack_nip)

• Self-serve BYO: each tenant owns its Paystack merchant, keys, and live KYB. Tenant admins save a write-only secret key; the same key verifies inbound webhooks (there is no separate webhook secret).
• Webhook verify: Paybond verifies X-Paystack-Signature on the raw body; missing or invalid signatures are rejected and never fund an intent.
• Funding is a Dedicated Virtual Account (DVA) credit (charge.success on dedicated_nuban); terminal payout is a Transfer (NIP) — transfer.success → released, transfer.failed / transfer.reversed → refund/manual review.
• Availability: Console destinations and paybond paystack ready|doctor are available. Start in sandbox; live destinations require tenant-owned Paystack KYB and a paid Paybond plan. Setup walkthrough: Configure Paystack settlement.

Post-funding settlement

After the payee submits evidence and Paybond evaluates the completion rule, terminal money movement runs only from evidence_submitted state.

Variable-cost settlement is rail-specific

For managed completion_budget_v1 / cost_and_completion, requested_spend_cents is an authorized ceiling, not the final charge. Harbor validates the payee-signed evidence, stores its cost_cents, and derives the terminal amount from that stored evidence. For example, 20,000 cents authorized + 18,700 cents reported = 18,700 cents captured or released + 1,300 cents unused authorization released or voided. These are integer cents: 20,000 cents is $200.00, 18,700 cents is $187.00, and 1,300 cents is $13.00.

Callers cannot submit or override the settlement amount on settlement/confirm. They also cannot supply a tenant or provider destination: authenticated tenant context and the intent's server-owned destination snapshot control routing. Fixed-price templates continue to settle the full authorized amount when their completion rule passes.

Do not infer universal partial-settlement support from a rail's fixed-price release path. Unsupported variable-cost combinations fail before capture, transfer, or payout so Paybond does not strand an unrecoverable remainder.

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 — Fixed-price release issues a Coinbase full capture against the authorized session; refund voids the authorization. Variable-cost settlement is rejected pre-effect.
• stripe_mpp charge — The one-shot charge is already committed for the full intent amount during funding, so variable-cost settlement is rejected pre-effect.
• stripe_mpp session — Cumulative vouchers already meter consumed spend; Harbor does not run the terminal rail driver for session intents.

Application teams call POST /intents/{id}/settlement/confirm (or Kit equivalents) after evidence evaluation. Paybond derives release vs refund and, for managed variable-cost policies, the amount from the stored validated evidence — callers choose neither 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

Response principles:

• Do not force an intent to funded outside the normal funding path — keep provider ids intact and retry /fund, or wait for webhooks and automatic reconcile.
• ACH: never treat the intent as funded while Stripe still reports a pending bank-debit state.
• x402: confirm Coinbase delivered the authorization webhook to Paybond before escalating.

Webhook delivery failure

Paybond verifies provider signatures and processes each event once (idempotent by provider event id).

What to check:

• Console: Settlements webhook health for Stripe delivery and processing status.
• Provider dashboard: delivery retries and response codes for the Paybond webhook endpoint.
• Intent detail: whether funding or terminal settlement advanced after the event.

Events missing metadata.tenant_id or metadata.paybond_intent_id are held for manual review and do not advance the intent. Ensure Stripe PaymentIntents include Paybond metadata at funding time.

Sandbox vs production

Sandbox ACH uses Paybond simulator routing (no Stripe test secret required). Sandbox MPP uses Stripe test mode once you paste a profile_test_... profile id in Settlement settings — see Fund intents on Stripe MPP.

Tenant isolation reminder

Every API call must carry tenant scope from authenticated credentials (API key or signed-in console session). Webhooks are bound to your tenant and destination before they advance an intent. Cross-tenant destination mismatch is rejected.

Where to go next