Configure settlement rails

In short: this is where a tenant admin tells Paybond which real payment rails it may use, before any agent spend can be funded. Before production intents can fund, a tenant admin configures which settlement rails the workspace may use. Paybond resolves destinations server-side from this configuration — client SDKs request an allowed rail; they do not supply Stripe account ids, Adyen API keys, or wallet addresses at funding time.

This guide covers Step 0 of How intent funding works. After rails are ready, application teams create and fund intents — see Fund intents by rail.

Console workspace

Open Configuration → Settlement (/console/configuration/settlement) as a tenant admin.

From here you can:

• Inspect the active settlement configuration and linked Stripe destination state
• Connect or refresh a Stripe Connect destination for card, ACH, and MPP rails
• Configure Stripe MPP profile id and optional Tempo session recipient settings
• Register the canonical Base USDC receive address for stablecoin settlement
• Choose which rails are allowed for new intents (stripe_connect, stripe_ach_debit, stripe_mpp, x402_usdc_base, Shopify rails, adyen_manual_capture)

Configuration changes create immutable versions for audit. The same state is available through GET /v1/admin/settlement/config for programmatic inspection. Tenant admins receive editable raw MPP and x402 addresses from that API; read-only principals see masked values only.

Supported rails

You select the rail per intent at create time (settlement_rail / settlementRail). The intent binds to that rail; Paybond snapshots the resolved destination from tenant configuration.

Stripe Connect setup

1. In the settlement console, start Connect onboarding for the tenant environment (sandbox vs production are separate).
2. Complete Stripe OAuth so Paybond can link the tenant-owned Connect destination.
3. Confirm the linked account appears as active in settlement config.
4. Add stripe_connect to allowed rails if card-funded intents should be permitted.

For stripe_connect, funding often completes during intent create when Stripe authorizes the PaymentIntent. Application teams may receive capability_token in the same response.

ACS manual capture

Merchants using Stripe Agentic Commerce Suite with Paybond conditional settlement should enable manual capture in the Stripe Dashboard under Agentic commerce settings. That keeps PaymentIntents authorized until Paybond drives capture (or cancel) on drive_terminal_settlement after the completion rule is evaluated — the same hold/capture model as stripe_connect.

Stamp ACS checkout PaymentIntents with Kit buildPaybondStripeMetadata so webhooks bind to the Paybond intent. Details: Paybond with Stripe agentic commerce.

ACH debit (stripe_ach_debit)

ACH uses the same linked Stripe destination but follows delayed-confirmation funding:

1. Ensure Connect onboarding is complete.
2. Wait until the console shows ACH debit capability ready for that destination.
3. Add stripe_ach_debit to allowed rails.

Intents on this rail may stay unfunded until Stripe confirms the bank debit. Application code should poll intent state or wait for webhooks rather than assuming immediate capability_token on create.

x402 USDC on Base (x402_usdc_base)

Stablecoin settlement uses Coinbase payment sessions on Base:

1. Decide the tenant-owned Base receive address for the environment (Base Sepolia for sandbox; production Base for live).
2. Save that address in settlement configuration through the console — not in application env vars exposed to agents.
3. Add x402_usdc_base to allowed rails.

Paybond operates the Coinbase connection and webhook delivery for hosted environments. Tenant admins only configure the receive address and allowed rails.

Intent amounts remain USD-denominated (cent-based budgets). The rail settles that value in USDC on Base.

Stripe MPP (stripe_mpp)

Machine Payments Protocol funding uses Payment Auth on POST /harbor/intents/{id}/fund. MPP routes through your linked Stripe destination. Configure MPP fields in Configuration → Settlement.

1. Complete Stripe Connect onboarding (same linked destination as card and ACH rails).
2. In Settlement settings, enter your Stripe MPP profile id:
   • Sandbox: use profile_test_... from the Stripe Dashboard.
   • Production: use a live profile_... id (not profile_test_...).
   • The console disables the stripe_mpp rail toggle until a profile id is saved.
3. For Tempo session funding (optional), set:
   • Tempo recipient address (canonical 0x followed by 40 hex), then
   • Enable Tempo session funding. Session mode requires a valid recipient.
4. Add stripe_mpp to allowed rails and save.

The same fields are available on PUT /v1/admin/settlement/config for automation. Paybond snapshots the resolved profile, recipient, and session flag onto each new intent — client create payloads must not supply MPP routing.

Production MPP uses Stripe live mode. For Tempo session funding in production, deposits confirm on Tempo mainnet. In sandbox, MPP uses Stripe test mode — paste your profile_test_... profile id in Settlement settings before enabling the rail.

Sandbox simulators

Sandbox tenants do not use live Stripe or Coinbase destinations. Paybond provides simulator routing so teams can:

• Create intents on approved sandbox rails
• Record simulator funding, release, refund, and dispute events
• Exercise console and Kit flows without moving real money

Use paybond.guardrails.bootstrapSandbox(...) or Gateway POST /v1/sandbox/guardrails/bootstrap for the fastest funded sandbox intent when integrating spend guard middleware.

Checklist before first production fund

• Paid plan activated and production API keys issued
• Settlement config saved with correct allowed rails
• Stripe Connect linked (for card and/or ACH) or Base address registered (for USDC)
• ACH capability marked ready if using stripe_ach_debit
• MPP profile configured and stripe_mpp allowed if using Machine Payments Protocol
• Application uses tenant-derived credentials — not client-supplied tenant ids
• Provider webhooks configured for the rails you use (Stripe, Coinbase, Adyen, Flutterwave as applicable)
• ACS manual capture enabled in Stripe Agentic commerce settings when using conditional Paybond release
• Adyen destination saved and adyen_manual_capture allowed if using BYO Adyen Checkout; confirm with paybond adyen doctor (Configure Adyen settlement)
• Flutterwave destination saved and flutterwave_virtual_account allowed if using BYO Flutterwave VA settlement; confirm with paybond flutterwave doctor (Configure Flutterwave settlement)
• Plaid Auth enabled and a ready bank linked if funding stripe_ach_debit via Plaid; confirm with paybond plaid doctor (Configure Plaid bank verification); Financial Connections remains the non-Plaid ACH path

Where to go next