Feature/int 1692 - Top-up instructions and amount allocations

[david-ruiz-cko]

This pull request adds support for retrieving top-up bank instructions for sub-accounts (currency accounts) via a new method in the Balances API, including configuration changes and comprehensive unit tests. It also documents a new request field in payment sessions. The main focus is ensuring the correct URL is used for the new endpoint, which does not follow the existing /balances path convention.

Key changes include:

Balances API Enhancements:

• Added a new retrieveTopUpInstructions method to the Balances class, allowing retrieval of bank details and payment references needed to top up a sub-account. This method uses a new configuration property to target the correct base URL for the endpoint.
• Updated the configuration (src/config.js and src/special-urls.js) to introduce balancesHostUrl, distinguishing it from the standard balancesUrl, so endpoints not under /balances are correctly addressed. [1] [2]

Testing:

• Added a new unit test suite (test/balances/balances-topup-unit.js) covering successful retrievals (including different bank details scenarios) and error handling for authentication and not found errors.

Documentation:

• Updated JSDoc comments for the new retrieveTopUpInstructions method to describe its parameters, response shape, and usage notes.
• Documented the new amount_allocations field in the payment sessions API.

Minor Refactoring:

• Changed a let to const for queryParams in the retrieve method of Balances for code consistency.

[agent-wall-e]

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

• no_low_class_matched
• prod_source_modified

Operational gates

• ✅ jira_ticket (INT-1692)
• ✅ independent_review

Files analysed: 6

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
no_low_class_matched	informational	§2.2 (fall-through)	None of the deterministic Low classes (§2.2.3, §2.2.4, §2.2.7, docs-only) applied; classifier fell through to LLM evaluation.
prod_source_modified	informational	§2.1 M7 (informational)	At least one file is non-doc, non-test, non-IaC — i.e. application source code was modified.

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🟠 Advisory review: Concerns worth a look

This PR needs a human approval. Before you give it, these are the things I'd want resolved.

Adds a retrieveTopUpInstructions method to the Balances class and refactors all URL string literals to named constants across many files; however, the existing retrieve method has a potentially breaking URL change that inserts an extra /balances segment, and the config files that would confirm whether this is correct are omitted from the diff.

Concerns

• In balances.js, retrieve now builds ${this.config.balancesUrl}/${BALANCES_PATH}/${id} — if balancesUrl still resolves to a URL already ending in /balances (its previous meaning), this produces a doubled /balances/balances/{id} path and is a breaking regression for all existing callers.
• The diff for src/config.js and src/special-urls.js is omitted, making it impossible to verify whether balancesUrl was redefined as a host-only root (which would make both URL constructions correct) or left unchanged (which would make retrieve broken).
• The PR description mentions a new balancesHostUrl property distinct from balancesUrl, but retrieveTopUpInstructions uses balancesUrl — if balancesHostUrl is the intended property for non-/balances paths, this method may be using the wrong config key.
• The new retrieveTopUpInstructions method uses this.config.sk as the auth token; confirm this is correct for the top-up instructions endpoint (not access or another token).

⚠️ The diff was too large to read in full, so this review covers only part of the change.

---

_{This is not an approval. wall-e cannot auto-approve this PR — it is an opinion to help whoever does. Advisory review · us.anthropic.claude-sonnet-4-6 · wall-e 2026.06.19-02}

[agent-wall-e]

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

• no_low_class_matched
• prod_source_modified

Operational gates

• ✅ jira_ticket (INT-1692)
• ✅ independent_review

Files analysed: 6

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
no_low_class_matched	informational	§2.2 (fall-through)	None of the deterministic Low classes (§2.2.3, §2.2.4, §2.2.7, docs-only) applied; classifier fell through to LLM evaluation.
prod_source_modified	informational	§2.1 M7 (informational)	At least one file is non-doc, non-test, non-IaC — i.e. application source code was modified.

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:src/api/issuing/cardholders.js
• security_sensitive_path:src/api/sessions/sessions.js
• security_sensitive_path:src/api/tokens/tokens.js

Operational gates

• ✅ jira_ticket (INT-1692)
• ✅ independent_review

Files analysed: 68

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — src/api/issuing/cardholders.js	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — src/api/sessions/sessions.js	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — src/api/tokens/tokens.js	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:src/api/issuing/cardholders.js
• security_sensitive_path:src/api/sessions/sessions.js
• security_sensitive_path:src/api/tokens/tokens.js

Operational gates

• ✅ jira_ticket (INT-1692)
• ✅ independent_review

Files analysed: 68

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — src/api/issuing/cardholders.js	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — src/api/sessions/sessions.js	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — src/api/tokens/tokens.js	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud