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

[david-ruiz-cko]

This pull request adds support for retrieving top-up instructions for balances sub-accounts, including new models, client methods, and tests. It also improves serialization for new query parameters and updates OAuth scopes.

Balances API enhancements:

• lib/checkout_sdk/balances/balances_client.rb: Added the retrieve_top_up_instructions method to fetch bank details and payment references for sub-account top-ups. Also added new endpoint constants and improved documentation for retrieve_entity_balances.
• lib/checkout_sdk/balances/top_up_instructions.rb, lib/checkout_sdk/balances/top_up_bank_details.rb, lib/checkout_sdk/balances/top_up_funding_details.rb: Introduced new model classes to represent top-up instructions, bank details, and funding rails. [1] [2] [3]

Query serialization improvements:

• lib/checkout_sdk/json_serializer.rb: Added camelCase mappings for with_currency_account_id and balances_at to ensure correct API requests.

OAuth scope updates:

• lib/checkout_sdk/oauth_scopes.rb: Added the new balances:top-up-instructions scope required for the new endpoint.

Testing:

• spec/checkout_sdk/balances/balances_client_spec.rb: Added unit tests for the new client method and serialization logic.
• spec/checkout_sdk/balances/balances_integration_spec.rb: Added integration tests for retrieving top-up instructions, handling both success and documented error responses.

[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:lib/checkout_sdk/oauth_scopes.rb

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 — lib/checkout_sdk/oauth_scopes.rb	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 the Balances client, three new model classes, camelCase serialization mappings for two existing query parameters, a new OAuth scope constant, and matching unit/integration tests. The implementation is correct and consistent with its stated intent.

What I checked

• The guard clauses in retrieve_top_up_instructions correctly use to_s.strip.empty? to catch nil, empty, and whitespace-only inputs before any network call is made.
• The URL path built from the four constants (ENTITIES / entity_id / CURRENCY_ACCOUNTS / currency_account_id / TOP_UP_INSTRUCTIONS) matches the documented API path in the integration test and inline comments.
• The new KEYS_TRANSFORMATIONS entries (with_currency_account_id → withCurrencyAccountId, balances_at → balancesAt) are consistent with camelCase convention used by the existing mappings and are pinned by a unit test.
• The integration test defensively skips rather than fails when no currency_account_id is available, and accepts 403/404 as documented outcomes while still failing on 400/401 — this is a reasonable trade-off for a sandbox environment.
• The new model classes (TopUpInstructions, TopUpBankDetails, TopUpFundingDetails) are plain structs with attr_accessor; they are consistent with the pattern of other model classes in the codebase.
• The flow_client.rb change is a documentation-only addition and does not alter any logic.
• The require order in balances.rb correctly loads top_up_funding_details before top_up_bank_details before top_up_instructions, matching their dependency chain.

---

_{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:lib/checkout_sdk/oauth_scopes.rb
• security_sensitive_path:spec/checkout_sdk/oauth_scopes_spec.rb

Operational gates

• ✅ jira_ticket (INT-1692)
• ✅ independent_review

Files analysed: 11

---

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