Skip to main content
The Bank Transfer plugin splits configuration across three levels. You can change most business settings at runtime, with no service restart. The tenant identity and the Midaz organization scope serve different purposes. Keep them distinct. The tenantId JWT claim in the authenticated request context resolves the tenant. The tenant controls infrastructure-level isolation: it selects the multi-tenancy platform database and grants access to tenant-scoped secrets. The X-Organization-Id header defines the Midaz organization scope inside that tenant. Every organization-scoped transfer route requires this header, in all deployment modes. A request returns 400 if it omits the header or sends a value that is not a valid UUID. Background processes, such as the TED IN poller and reconciliation workers, do not receive request headers. In single-tenant deployments, these processes use the ORGANIZATION_ID environment variable as the organization context.

​
Configuration levels

The Bank Transfer plugin has three configuration levels:
  • Infrastructure configuration (DevOps manages it) controls URLs, credentials, authentication settings, and timeouts. Changes need a service restart.
  • Tenant settings (the Product team manages them through the Admin API) control transfer limits, fee policies, and operating-hours overrides. Changes take effect with no service restart.
  • Account settings (the Product team manages them through the Admin API) control limits and restrictions for individual accounts. Changes take effect with no service restart.

​
Business decisions you can configure

GPMs and product teams care about these settings. You manage all of them through the Admin API at runtime, with no deploy.

​
Transfer limits

Set daily and monthly volume caps at two levels:
  • Per organization — applies to transfers for one Midaz organization inside the resolved tenant
  • Per account — applies to a specific end-user account (overrides organization defaults)
Limits cover both total amount and number of transactions. Set these to manage risk and comply with BACEN requirements.

​
Fee policy

Control whether the plugin charges a fee on TED OUT, TED IN, and P2P transfers. The Fees Engine defines the fee rules and applies them per organization. See Fees Engine for configuration details.

​
Fail-open vs. fail-closed

If the fee calculation service is unavailable when a transfer runs, you have two options:
  • Fail-open — allow the transfer to proceed without a fee
  • Fail-closed — block the transfer until the fee service is available again
The default fee-service policy is fail-open (FEES_FAIL_CLOSED_DEFAULT=false). Change it per organization through the Admin API when you need fee-service outages to block transfers. TED IN has its own safety switch, BTF_FEES_TED_IN_FAIL_OPEN, which defaults to true. If plugin-fees is down, the plugin credits inbound funds with fee=0.

​
TED IN receiving

Incoming transfers stay disabled by default. Enable TED IN per organization after you configure your JD SPB credentials and start the polling worker.

​
Operating hours overrides

The plugin enforces BACEN’s TED operating window by default. You can set custom windows per tenant policy within BACEN limits — for example, transfers during business hours only.

​
Infrastructure configuration

DevOps sets the deploy-time environment variables (URLs, credentials, TLS, persistence, integrations, security keys). These variables require a service restart. See the full reference in Environment variables.

​
Runtime configuration (Admin API)

You manage tenant-level and account-level settings through the Admin API, with no restart. Changes take effect immediately (subject to the cache TTL for tenant settings). Configurable settings include:
  • Transfer limits (daily and monthly, per organization and per account)
  • Fee behavior (fail-open or fail-closed when the fee service is unavailable)
  • TED IN receiving (enabled or disabled per organization)
  • Operating hours overrides (custom windows within BACEN limits)
See the Admin API reference for the full list of configurable fields and request format.

​
Systemplane-managed settings

The systemplane (Admin API) manages the settings below at runtime, not at deploy time. Each one has a matching environment variable name that still exists in the codebase. The config loader ignores these env vars and logs a deprecation WARN if you set them. Assigning them through the environment has no effect. Use the systemplane to change them.
Setting any of the names above through the environment has no effect. The loader logs a deprecation WARN instead. These names exist only as deprecated env twins of runtime/systemplane-managed settings.
When CORS is unconfigured, the default allowed origin is the wildcard *. Any origin can then call the API, and the plugin does not validate it at startup. For production, set explicit origins through the systemplane key cors.allowed_origins instead of the wildcard.