ADR-015: Cross-border NZ/AU wallet and transfer design¶
| Status | Accepted |
| Date | 2026-04-10 |
| Deciders | CTO, Head of Product, Head of Payments, CFO |
| Affects repos | bank-core, bank-payments, bank-app, bank-risk-platform |
Status¶
Accepted — 2026-04-10
Scope assumption¶
This ADR applies exclusively to the bank business model — specifically the scenario (Option A in PRD-004) where the organisation operates as a single licensed deposit-taking institution holding customer accounts in both NZ and AU under the same legal entity or branch structure.
The core architectural claim of this ADR — that a NZD↔AUD transfer is an internal journal entry requiring no external payment instruction — only holds under that assumption. If both accounts are within the same bank, there is no interbank settlement, no correspondent channel, and no external payment. That is why the latency, cost, and regulatory exposure are all minimised.
This ADR does not apply to a SaaS / inter-institutional model. In a SaaS scenario, NZD accounts are held at one institution (a platform tenant in NZ) and AUD accounts at a separate institution (a platform tenant in AU). A transfer between them is an inter-institutional settlement, not an internal journal entry. The internal FX nostro design in this ADR has no meaning across separate legal entities.
The SaaS alternative — a customer-level Vostro construct with KYC attestation via FATF Recommendation 17 and a CDD reliance agreement between tenant institutions — is documented as Option B in PRD-004. Option B requires its own ADR before any design or build commences. The outstanding items before that ADR can be raised are listed in PRD-004 (CDD reliance agreement, AU licensing, attestation API, inter-institutional FX settlement, wallet regulatory classification).
Context¶
The cross-border NZD↔AUD wallet is a primary differentiator for this bank. Customers who live, work, or travel between NZ and AU currently face high fees, slow settlement times, and opaque exchange rates when moving money between the two countries. The bank's dual-jurisdiction structure creates a unique opportunity: both accounts are held within the same bank, so a cross-border transfer is an internal journal entry rather than an international payment.
This ADR documents the data model, settlement mechanics, FX rate design, regulatory reporting obligations, and the UX principles that make this capability genuinely competitive.
Decision¶
Cross-border NZD↔AUD transfers are implemented as internal journal entries against two currency ledgers, routed through an internal FX nostro pair. No SWIFT, no correspondent banking, no T+2 settlement. Rate lock provided for 30–60 seconds. IFTI (AU) and CMIR (NZ) reporting automated via Snowflake pipeline. FX spread disclosed transparently before confirmation.
Data model foundation¶
A single customer record in Postgres links to multiple account records, each tagged with a currency (NZD or AUD) and jurisdiction (NZ or AU). The cross-border transfer service treats both accounts as internal — it never generates an external payment instruction.
This is the architectural advantage that traditional banks cannot easily replicate. Legacy banks maintain separate NZ and AU ledgers in separate core banking systems. We have one ledger, two currencies.
Ledger entries for a NZD 500 → AUD transfer¶
A single Postgres transaction writes four entries atomically:
Dr customer.nzd_account NZD 500.00
Cr bank.internal_nzd_fx_nostro NZD 500.00
Dr bank.internal_aud_fx_nostro AUD 461.65 (at locked rate)
Cr customer.aud_account AUD 461.65
The internal FX nostro pair nets to zero in the bank's overall position. The bank's aggregate FX exposure is the sum of all customer conversions — which is hedged in the interbank market at the treasury level, not at the individual transaction level.
FX rate design¶
Rate sourcing¶
Live mid-market rate sourced from a market data feed (Reuters Elektron, Bloomberg B-PIPE, or equivalent bank API). The bank applies a spread on top of the mid-market rate.
Spread policy¶
For an intra-bank wallet transfer between the same customer's accounts, a spread of 0.5–1.0% is both commercially meaningful and competitive. The spread must be disclosed explicitly to the customer before they confirm — not buried in an exchange rate. This is both a regulatory requirement and a commercial differentiator.
The FX transparency model: show the mid-market rate, show the spread explicitly, show the all-in cost. Wise (TransferWise) built its entire brand on this approach. Customers respond positively, and it differentiates the bank from incumbents who bury FX margins in opaque exchange rates.
Rate lock¶
The customer is offered a locked rate for 30–60 seconds to prevent gaming during a quote. After the lock expires the rate refreshes. If the customer confirms within the window, execution happens at the locked rate regardless of market movement — this is the bank's execution risk, managed by the spread buffer and the fact that NZD/AUD is a low-volatility pair.
UX design principles¶
The cross-border transfer flow must show: 1. Amount being sent (NZD) 2. Live exchange rate (mid-market) 3. Bank spread (shown explicitly as a percentage and amount) 4. Amount received (AUD) 5. Settlement time (target: instant or near-instant) 6. A countdown timer showing the rate lock expiry 7. A confirm button that is only available while the rate is locked
The customer must not be able to confirm a transfer without seeing the full cost including spread. This is enforced as a disclosure gate (MOD-050) — the confirmation screen cannot be reached without the disclosure screen being displayed and acknowledged.
Customer experience — both accounts visible together¶
A customer with NZ and AU accounts sees both on their home screen, converted to a common NZD equivalent for the total balance display. The account switcher in the transaction history shows all four accounts (NZ Everyday, NZ Savings, AU Everyday, AU Savings). Switching between them is instant — no separate login, no separate app.
Cross-border transfers that appear in the NZD account show the AUD amount received as metadata in the transaction detail. The AU account shows the NZD source and the FX rate applied. Both sides of the conversion are visible to the customer without needing to cross-reference two separate transaction histories.
Regulatory reporting obligations¶
Both AUSTRAC (AU) and the RBNZ require reporting of international funds transfer instructions: - AU: IFTI (International Funds Transfer Instruction) — AUD 1,000 threshold, must be submitted within 10 business days - NZ: CMIR (Cross-border Monetary Instrument Reports) — NZD equivalent threshold
Even though this is an internal wallet transfer, if the customer's two accounts are booked in different legal entities (NZ registered bank and AU branch/subsidiary), it may constitute a reportable cross-border transfer. Legal advice on the specific entity structure is required to confirm reporting obligations.
Implementation: The Snowflake pipeline (MOD-026) automatically identifies and batches IFTI/CMIR reportable transfers from the event stream. No manual process. The trigger fires on every cross-border conversion event; qualifying transfers are tagged, formatted, and submitted to AUSTRAC and RBNZ on schedule.
FX hedging strategy¶
As transfer volumes grow, the aggregate NZD/AUD book accumulates an open FX position. The treasury function requires a policy that defines: - At what notional size the bank hedges (the hedging threshold) - At what frequency (daily, weekly, or continuous) - Through which counterparty (clearing bank or FX prime broker)
NZD/AUD is highly correlated and relatively stable, which reduces hedging urgency at low volumes. The policy must be in place before launch, even if the initial hedging threshold is set conservatively high for the startup phase.
Decision required: Treasury policy for FX hedging — threshold, frequency, counterparty. This is separate from the technology decision documented here but must be resolved before go-live.
Principles alignment¶
| Principle | Assessment | Notes |
|---|---|---|
| AP-001 KISS | ✓ | Internal journal entry is simpler than external payment infrastructure |
| AP-002 Data governance | ✓ | FX rate, spread, and both conversion amounts logged immutably |
| AP-003 Compliance | ✓ | IFTI/CMIR reporting automated — cannot be missed |
| AP-004 Security | ✓ | Atomic transaction — partial conversion cannot occur |
| AP-005 Customer driven | ✓ | Transparent FX, instant settlement, single app for both currencies |
| AP-008 Real time | ✓ | Rate lock and instant settlement are genuine real-time requirements |
Perspectives¶
| Perspective | Assessment | Notes |
|---|---|---|
| Performance & Scalability | ✓ | Internal journal entry is faster than any external payment |
| Strategy | ✓ | Primary product differentiator; not easily replicated by legacy incumbents |
| Integration | ✓ | FX nostro design separates conversion risk from individual transactions |
| Regulatory | ~ | IFTI/CMIR obligations require legal advice on entity structure |
| Risk | ~ | FX position management requires treasury policy before launch |
| Usability | ✓ | Rate transparency and single-app experience are core to the value proposition |
See perspectives.md for how to use these evaluation lenses.
Relevant viewpoints¶
- Functional viewpoint — NZD↔AUD transfer flow from customer initiation to confirmation
- System viewpoint — FX nostro pair in ledger; rate lock service; dual-ledger atomic post; IFTI/CMIR reporting pipeline
- Information viewpoint — Ledger entry schema for FX conversions; FX nostro reconciliation structure
- Security viewpoint — Atomic transaction integrity; rate lock implementation; FX exposure management
- Operational viewpoint — FX nostro reconciliation; IFTI/CMIR submission monitoring; hedging position dashboard
See viewpoints.md for guidance on producing these viewpoints.
Signoff record¶
| Date | Name | Role | Status |
|---|---|---|---|
| 2026-04-10 | Ross Millen | CTO | Approved |
| 2026-04-10 | Ross Millen | Head of Architecture | Approved |
| 2026-04-10 | Ross Millen | Head of Data | Approved |
Capabilities¶
| Capability | Description | Relationship |
|---|---|---|
| CAP-003 | Multi-currency wallet (USD, EUR, GBP, SGD, JPY) | architecturally required — NZD/AUD internal wallet is the foundation |
| CAP-006 | Foreign exchange — live rates, rate lock | enabled — live mid-market rate, spread disclosure, and 30–60s rate lock defined here |
| CAP-011 | Real-time balance & transaction feed | enabled — both NZD and AUD account legs visible in real time |
| CAP-042 | Fee-free international transfers up to threshold | governed — spread policy (0.5–1%) and threshold structure defined here |
| CAP-043 | Transparent FX markup display | enabled — explicit spread disclosure before confirmation is an architectural constraint |
| CAP-129 | Internal FX nostro management | enabled — FX nostro pair, hedging threshold, and treasury FX policy defined here |
Related decisions¶
| ADR | Title | Relationship |
|---|---|---|
| ADR-001 | Postgres as the OLTP operational store | atomic four-entry journal entry in Postgres is the mechanism |
| ADR-005 | Payments partner at launch — direct scheme membership deferred | internal journal entry bypasses the payments partner |
All ADRs
Compiled 2026-05-22 from source/entities/adrs/ADR-015.yaml