feature/INT-1692 - Top-up instructions and amount allocations

[david-ruiz-cko]

This pull request adds support for retrieving top-up instructions for currency accounts via the balances API, enhances the BalancesQuery filter with improved typing and serialization, and introduces comprehensive tests to ensure correct serialization and response handling. It also adds a new OAuth scope for top-up instructions and updates the test coverage accordingly.

Balances API enhancements:

• Added a new method retrieve_top_up_instructions to BalancesClient for fetching top-up instructions for a specific currency account, and defined the required endpoint paths. [1] [2]
• Updated BalancesQuery to use correct types: with_currency_account_id is now a boolean and balances_at is a datetime, with improved docstrings and comments for clarity.

OAuth and authorization:

• Added the balances:top-up-instructions OAuth scope to OAuthScopes and included it in the default OAuth API test client configuration. [1] [2]

Testing and serialization:

• Implemented new integration and unit tests for the top-up instructions endpoint, including response-shape tests and serialization checks for BalancesQuery to ensure correct camelCase mapping and ISO date formatting. [1] [2] [3]

Other SDK improvements:

• Added an amount_allocations field to SubmitPaymentSessionRequest to support allocation of amounts in payment sessions.

[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:checkout_sdk/oauth_scopes.py
• security_sensitive_path:checkout_sdk/payments/sessions/sessions.py

Operational gates

• ✅ jira_ticket (INT-1692)
• ✅ independent_review

Files analysed: 8

---

_{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 — checkout_sdk/oauth_scopes.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — checkout_sdk/payments/sessions/sessions.py	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]

🟢 Advisory review: Looks good to me

This PR still needs a human approval — wall-e cannot auto-approve it. For what it's worth, I read the diff and found nothing I'd block on.

Adds retrieve_top_up_instructions to BalancesClient, fixes types on BalancesQuery, adds the new OAuth scope, adds amount_allocations to SubmitPaymentSessionRequest, and covers all changes with unit, serialization, and integration tests. The implementation looks correct and complete for what is shown.

What I checked

• Path construction in retrieve_top_up_instructions uses build_path with four path segments and no query object, which is consistent with the existing retrieve_entity_balances pattern.
• Blank/None guard on both path parameters raises CheckoutArgumentException before any network call, and the parametrized test verifies all six edge cases including the whitespace-only case.
• The integration test correctly handles the sandbox-always-returns-403 case by accepting 403/404 but still failing on 400 (malformed path) and 401 (auth problem), which are the two real SDK failure modes.
• BalancesQuery.with_currency_account_id corrected from str to bool and balances_at from str to datetime; the serialization tests pin the camelCase wire names (withCurrencyAccountId, balancesAt) so a regression in JsonSerializer._KEYS_TRANSFORMATIONS would be caught.
• amount_allocations added to SubmitPaymentSessionRequest as a class-level annotation only (no default), and the serialization test confirms it is omitted when unset rather than serialized as null, which matches the stated API constraint.
• The new OAuthScopes.BALANCES_TOP_UP_INSTRUCTIONS value 'balances:top-up-instructions' is pinned by a unit test and added to the integration test fixture's scope list.

⚠️ 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: MAJOR

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

Classification reasons

• security_sensitive_path:checkout_sdk/oauth_scopes.py
• security_sensitive_path:checkout_sdk/payments/sessions/sessions.py

Operational gates

• ✅ jira_ticket (INT-1692)
• ✅ independent_review

Files analysed: 8

---

_{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 — checkout_sdk/oauth_scopes.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — checkout_sdk/payments/sessions/sessions.py	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:checkout_sdk/oauth_scopes.py
• security_sensitive_path:checkout_sdk/payments/sessions/sessions.py
• security_sensitive_path:tests/oauth_scopes_test.py
• security_sensitive_path:tests/payments/sessions/payment_sessions_serialization_test.py

Operational gates

• ✅ jira_ticket (INT-1692)
• ✅ independent_review

Files analysed: 10

---

_{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 — checkout_sdk/oauth_scopes.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — checkout_sdk/payments/sessions/sessions.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/oauth_scopes_test.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/payments/sessions/payment_sessions_serialization_test.py	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:checkout_sdk/oauth_scopes.py
• security_sensitive_path:checkout_sdk/payments/sessions/sessions.py
• security_sensitive_path:tests/oauth_scopes_test.py
• security_sensitive_path:tests/payments/sessions/payment_sessions_serialization_test.py

Operational gates

• ✅ jira_ticket (INT-1692)
• ✅ independent_review

Files analysed: 10

---

_{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 — checkout_sdk/oauth_scopes.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — checkout_sdk/payments/sessions/sessions.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/oauth_scopes_test.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/payments/sessions/payment_sessions_serialization_test.py	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
0 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