paybondpaybond
Sign in

Integration · Stripe

Configure Plaid bank verification

Tenant-admin guide: enable Plaid Auth as bank verification under stripe_ach_debit, link banks in Console Settlement, and confirm readiness with paybond plaid ready|doctor.

  • Plaid Auth
  • stripe_ach_debit
  • /webhooks/plaid
  1. 01Connect
  2. 02Configure
  3. 03Verify
  4. 04Go live

Plaid Auth is an optional bank-verification path for the existing stripe_ach_debit rail — not a separate settlement rail and not Plaid Transfer. Stripe remains the ACH money mover; Harbor funds an intent only when Stripe reports payment_intent.succeeded. Tenant admins link banks and fund intents; agents spend only after an intent is already funded.

Prerequisites

  1. A Paybond tenant with Stripe ACH configured for stripe_ach_debit (see Configure settlement rails).
  2. Plaid Auth available for your tenant (sandbox for testing; production after Paybond enables live Plaid for your workspace).
  3. A tenant role that can manage or view Plaid bank link (tenant admin for Link / exchange / revoke; Harbor-readable roles may list banks).

If Plaid is not yet available in your workspace, contact Paybond or your account team. Financial Connections remains the supported non-Plaid ACH path.

Console workspace

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

From the Plaid bank verification panel you can:

  • Start Plaid Link (the browser never receives bank access tokens or Stripe processor tokens)
  • See linked banks with institution name, masked account, last4, status, and readiness reason
  • Retry Stripe attach when status is retryable
  • Relink when Plaid reports that login is required again
  • Revoke a bank (it becomes non-debitable immediately; remote cleanup runs in the background)

On an ACH intent, the funding panel lets you select a ready Plaid bank or fall back to Stripe Financial Connections.

Security boundary

  • Tenant scope always comes from the authenticated session or API key — never from a tenant id in request JSON.
  • Console and CLI show safe metadata only (ids, masks, statuses, readiness reason codes).
  • Never paste Link tokens, access tokens, or account/routing numbers into tickets, logs, or CLI examples.
Status / reasonMeaningACH fund
readyAuth verified and Stripe bank source attachedAllowed for that bank
pending_automatic_verificationAutomated Micro-deposits in flightBlocked until Plaid verifies
attach_pending / attach_retryable / attach_failedStripe attach in progress, retryable, or failedBlocked until attach succeeds
relink_requiredRecoverable Item error (for example, login required)Blocked until Relink
revoked / verification_expired / errorTerminal or soft-revokedBlocked
risk_check_required / risk_check_failedHigher-value ACH risk policy gateBlocked — use Financial Connections or contact support
feature_disabled / production_not_allowlistedPlaid Auth is not enabled for this tenant or environmentUse Financial Connections; contact Paybond to enable

Financial Connections remains the supported non-Plaid ACH path when Plaid is off, pending, or blocked.

ACH risk-policy defaults

Paybond screens every positive-dollar Plaid-selected ACH debit with Signal, adds a real-time Balance requirement at $500, and adds Identity Match at $1,000. Default decision cutoffs:

ControlDefault
Identity Match legal-name scoreat least 70 / 100
Signal customer-return risk tierat most 2 / 5
Available-balance cushiondebit amount + $100
Decision freshness5 minutes

Unavailable, stale, or indeterminate results block the Plaid-selected debit; they never silently downgrade to Auth-only. Financial Connections or manual review remains the fallback.

The legal baseline is Nacha Article Two, Subsection 2.5.17.4 (WEB account validation, effective March 19, 2021) and the 2026 fraud-monitoring amendments (Phase 1 March 20; Phase 2 practical compliance date June 22, 2026). Plaid publishes 70 as its default recommended Identity Match threshold and directs Signal customers to tune cutoffs from reported decisions and ACH returns.

Webhooks

Paybond receives Plaid Auth status updates (for example, Automated Micro-deposit completion) on a single verified webhook route. You do not configure this URL yourself for managed Paybond environments — Paybond registers it with Plaid.

https://api.paybond.ai/webhooks/plaid

Do not use a retired production-scoped webhook path segment. Use /webhooks/plaid only. Webhooks update bank verification state and enqueue Stripe attach; they never fund Harbor directly.

To print the webhook address for your configured gateway (useful for self-hosted or staging setups):

Terminal
Terminal commandSwipe to inspect long lines
paybond plaid webhook-address
paybond plaid webhook-address --gateway https://staging.example.test

Try it in sandbox

  1. Confirm your tenant is on the sandbox environment with Stripe test mode configured for ACH.
  2. In Console Settlement, start Plaid Link and connect a sandbox Instant Auth institution. After Stripe attach, the bank should show ready.
  3. Optionally exercise Automated Micro-deposits with a sandbox pending institution; status moves to ready after verification completes.
  4. Confirm readiness from the CLI after paybond login:
Terminal
Terminal commandSwipe to inspect long lines
paybond plaid ready
paybond plaid doctor
paybond plaid banks list

Going live

Production Plaid Auth is enabled per tenant after Paybond and Plaid production Auth are ready for your workspace:

  1. Complete live Stripe ACH setup for stripe_ach_debit (see Configure settlement rails).
  2. Ask Paybond to enable live Plaid Auth for your tenant.
  3. Link a production bank with Instant Auth first, confirm ready, then fund a small ACH intent.
  4. Keep Financial Connections available as a fallback while you expand usage.

If the Console shows feature_disabled or production_not_allowlisted, Plaid is not yet enabled for your tenant — use Financial Connections and contact Paybond.

CLI inspection (paybond plaid)

After paybond login, use the Kit CLI for read-only readiness (never Link, never tokens on the command line):

Terminal
Terminal commandSwipe to inspect long lines
paybond plaid ready
paybond plaid doctor
paybond plaid banks list
paybond plaid banks get <bank-account-id>
paybond plaid webhook-address
  • plaid ready — feature available for this tenant and at least one bank with ready.
  • plaid doctor — expands ready with webhook address, environment pairing hints, and Console/docs pointers.
  • plaid banks list|get — safe bank metadata and readiness_reason only.
  • Rejected on the command line: --public-token, --access-token, --link-token, --processor-token, --bank-account-token.

Next steps