# BidFlo × Fintech — implementation-neutral discovery requirements

**Proposed architecture · not implemented · October 26, 2026**

The existing fintech platform supplies customer and account relationships, distribution, supported identity and payment services. BidFlo supplies the project workflow. Every new connection—provisioning, SSO, data exchange, invoice mapping, callbacks and payment processing—is a separately scoped, unimplemented proposal. Existing Stripe is unchanged.

## Define responsibilities before interfaces

Agree customer and product fit, supported geography and payment rails, merchant/payer responsibilities, onboarding and support, permitted data, consent and retention. Distinguish the software distribution/license agreement from any live payment authorization. No customer ownership, automatic access, certification or compliance guarantee is implied.

## Identity and data mapping

Jointly define scoped identity, tenant and user roles, consented customer links, environment separation and provisioning. Customer authorization cannot be inferred from a demo role tab or a tenant identifier. Establish authoritative mappings for project, selected contractor/payee, agreement, invoice revision, approval, currency and outstanding amount. Specific authentication protocols, API paths, scopes and event formats are intentionally not specified.

## Preserve payment decisions

Work review, approval of an issued invoice revision, payment-session preparation and payer authorization are separate. Before preparing one request, verify the consented customer link, exact approved revision, payee, currency and authoritative outstanding amount. Derive financial values from authoritative records rather than browser input.

Jointly define idempotency, concurrent creation controls and durable request/attempt records. An unresolved or unknown earlier attempt blocks a replacement attempt across invoice revisions until reconciled. A milestone, invoice edit or new browser session cannot bypass that uncertainty.

## Verify status and reconcile

Use the selected provider's actual, jointly validated callback/signature contract—not an invented signature header or a browser success URL. Define raw-body verification, replay handling, durable deduplication, resource ownership, out-of-order processing, retries and reconciliation. Keep collection, settlement, returns/refunds/disputes and Contractor payout as separate records; collection does not guarantee irrevocable settlement or payout.

## Sandbox and live gates

Use synthetic customers for validation and test wrong tenants, payees, currency/amount, changed or voided invoices, expired sessions, duplicate/concurrent requests, unknown outcomes, invalid signatures, replay, out-of-order updates, returns, refunds, disputes and payout independently. Test outcomes do not themselves grant live authority.

Any live pilot requires separately signed scope for precise customers, geography, rails, transaction types and monetary limits, customer/merchant terms, sandbox acceptance and legal/compliance/security/engineering sign-off. No rollout time, price, revenue, retention, fees, insurance, financing, escrow or instant payout guarantee is offered.

This document is a discovery framework, not an API reference, deployed security design, granted license or payment authorization. Original detailed internal drafts remain private.