A business-banking platform must expose payouts, balances, approvals and reconciliation to customer developers. How should the API surface be structured, and what determines what is exposed?

The structuring principle

Expose business operations, not internal state transitions. A customer wants to "create a payout to this beneficiary" — they do not want to orchestrate a sequence of internal steps whose ordering constraints are your implementation detail. Every internal step exposed is a contract you cannot change.

The corollary: the API is a product with its own lifecycle, and its shape should be driven by the jobs customers are doing rather than by the services behind it. An API that mirrors your service decomposition has exported your organisation chart to your customers.

What this domain specifically requires

• Approval workflows as first-class API concepts. A payout requiring two approvals is a business rule, not a client-side concern, and expressing it in the API is what makes the platform usable for a company with financial controls. If the customer must implement approvals themselves, they will implement them inconsistently.
• Idempotency on every mutating operation, since these move money and clients will retry.
• Explicit intermediate states. "Queued", "processing", "awaiting approval", "sent", "settled", "failed", "returned" — a payout genuinely passes through all of these and collapsing them into success/failure removes the customer's ability to build a correct experience.
• Reconciliation as a designed feature: statement endpoints, a stable transaction identifier that appears on both sides, and an export that matches the accounting view. Customers will reconcile whether or not you help them, and a platform that makes it hard generates support load and distrust.
• Webhooks for state transitions, since polling for the completion of an asynchronous financial operation scales badly for both parties.
• Permission scopes that map to real roles, because a business-banking customer has genuinely different roles — an initiator, an approver, a viewer, an auditor — and a single API key ignores the segregation of duties that their own controls require.

What determines what is exposed

Whether you can commit to it for years. An API is a promise, and in a financial product with regulated customers the promise is close to permanent — integrators cannot re-certify a change quickly.

That argues for exposing less initially and expanding deliberately, and for keeping anything volatile behind a stable façade. The most expensive API mistakes are things exposed early because they happened to exist, which then constrain the internal design for years.