Designing configurable international transfers without turning every new market into an application release.
International payment products often begin with country-specific code:
if country == "A":
require_bank_code()
elif country == "B":
require_iban()
This works for the first few corridors. It becomes fragile when one country supports several rails, a rail has different fees, funding is enabled before payout, or a provider temporarily disables a destination.
A more durable model separates four capabilities:
country availability
funding methods
payout methods
recipient requirements
A country can be active in the directory while funding remains disabled. A payout method can be available for one currency and unavailable for another. A bank rail can require an account number and routing code, while a wallet rail may require only a handle or an optional QR image.
Make recipient fields data-driven
The recipient form should come from a requirement schema attached to the selected country, currency, and payout method. Each field needs a stable key, label, type, validation rule, display order, and required flag.
This prevents a wallet recipient from being asked for an IBAN or a bank beneficiary from receiving irrelevant mobile fields. The backend must validate against the same schema. Client-side visibility alone is not a security or data-integrity boundary.
Keep provider routing behind the corridor
The customer chooses a destination and payout method, not an internal provider. Routing should resolve the configured provider after validating availability. Persist the selected route on the transaction so a later configuration change cannot reinterpret an existing payment.
Configuration changes should affect new quotes and transfers. Existing transactions should retain the provider, fee, exchange rate, destination snapshot, and requirements used when they were created.
Return capabilities through one contract
Mobile screens for send, deposit, and withdrawal should not maintain separate hard-coded country lists. A capabilities endpoint can return whether each action is enabled, supported currencies, methods, and recipient requirements.
Default selection can use the customer's location only when that country supports the requested action. Otherwise, choose an explicit product fallback and explain the selection rather than silently showing an unusable flow.
Audit operational changes
Staff should be able to activate or deactivate corridors and capabilities in bulk, but every change needs an actor, timestamp, previous value, and new value. High-impact changes should support staged activation and validation before becoming visible to customers.
Cache the directory for performance, but include a configuration version in the response and cache key. When staff switch a provider or change a bank directory, clients should receive the new version without requiring users to refresh repeatedly.
The architecture scales when adding a country is primarily a configuration and validation exercise, while the shared transaction state machine, ledger, and operational fallback remain unchanged.
Implementation checklist
Version corridor configuration and validate it before activation. Ensure every enabled payout method has a provider route, currency, fee rule, recipient schema, and fallback policy. Reject configurations that create an enabled customer path with no executable route.
Test the capabilities contract against each client version still in circulation. Add contract tests for required recipient fields and verify that old clients receive a safe unavailable response when they cannot render a newly introduced method. Operational flexibility should not create an invalid form on a previously released application.
Top comments (0)