Release 2.2.0 - Top-up instructions and amount allocations

[david-ruiz-cko]

This release 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: 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
• ✅ independent_review

Files analysed: 1

---

_{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: 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.

This PR adds top-up instructions support to the Balances API, including new model classes, client methods, serialization fixes, OAuth scopes, and tests, with a version bump to 2.2.0. The changes look correct and consistent with the stated intent.

What I checked

• New retrieve_top_up_instructions method follows the existing pattern in balances_client.rb with appropriate endpoint constants and documentation.
• New model classes (TopUpInstructions, TopUpBankDetails, TopUpFundingDetails) are straightforward data containers consistent with existing SDK model patterns.
• The json_serializer.rb camelCase mappings for with_currency_account_id and balances_at are a necessary fix for correct query parameter serialization to the API.
• The new balances:top-up-instructions OAuth scope in oauth_scopes.rb matches what the new endpoint would require.
• Unit and integration tests cover the new client method, including error response scenarios, providing adequate coverage for the new functionality.
• Version bump from 2.1.0 to 2.2.0 is consistent with the scope of changes (new features added).

---

_{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}

[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