genesis_ruby 0.3.1 → 0.3.2

data/.kiro/specs/f2025112603-add_reverify_endpoint_to_payee_account/design.md

@@ -0,0 +1,148 @@
+# Design Document
+
+## Overview
+
+This design adds a `Reverify` request class to the `GenesisRuby::Api::Requests::NonFinancial::Payee::Account` module. The class sends a `POST` request to `/payee/:payee_unique_id/account/:account_unique_id/reverify` with an empty JSON body `{}`, allowing SDK consumers to retry failed Payee Account verifications.
+
+The implementation follows the established patterns of the existing Account request classes (Create, Retrieve, Update, List) — inheriting from `Base::Versioned`, using the JSON builder, performing path-token substitution in `process_request_parameters`, and configuring the API service endpoint without a terminal token.
+
+## Architecture
+
+The Reverify class slots into the existing request hierarchy with no new abstractions:
+
+```mermaid
+classDiagram
+    class Request {
+        <<abstract>>
+        #init_configuration()
+        #process_request_parameters()
+        #init_api_service_configuration()
+        +build_document()
+    }
+    class Versioned {
+        <<abstract>>
+        #request_path
+        #request_structure()
+        #init_json_configuration()
+    }
+    class Reverify {
+        +payee_unique_id
+        +account_unique_id
+        #init_field_validations()
+        #request_structure()
+        #process_request_parameters()
+    }
+
+    Request <|-- Versioned
+    Versioned <|-- Reverify
+```
+
+The class uses the default `POST` HTTP method provided by `Base::Versioned` (via `init_json_configuration`). No HTTP method override is needed — unlike Retrieve/List (which override to `GET`) or Update (which overrides to `PATCH`).
+
+## Components and Interfaces
+
+### New File
+
+`lib/genesis_ruby/api/requests/non_financial/payee/account/reverify.rb`
+
+### Class: `GenesisRuby::Api::Requests::NonFinancial::Payee::Account::Reverify`
+
+**Superclass:** `GenesisRuby::Api::Requests::Base::Versioned`
+
+**Public interface:**
+
+| Member | Type | Description |
+|---|---|---|
+| `payee_unique_id` | `attr_accessor` | The unique identifier of the Payee |
+| `account_unique_id` | `attr_accessor` | The unique identifier of the Account |
+| `initialize(configuration, _builder_interface = nil)` | constructor | Sets `request_path` to `payee/:payee_unique_id/account/:account_unique_id/reverify` |
+
+**Protected methods:**
+
+| Method | Description |
+|---|---|
+| `init_field_validations` | Pushes `payee_unique_id` and `account_unique_id` onto `required_fields` |
+| `request_structure` | Returns `{}` (empty hash) |
+| `process_request_parameters` | Substitutes path tokens and calls `init_api_service_configuration` with `include_token: false` |
+
+### Auto-loading
+
+The file path `lib/genesis_ruby/api/requests/non_financial/payee/account/reverify.rb` matches the existing glob in `dependencies.rb`:
+
+```ruby
+Dir["#{File.dirname(__FILE__)}/api/requests/*financial/**/*.rb"].sort.each { |file| require file }
+```
+
+No changes to `dependencies.rb` are needed.
+
+### New Test File
+
+`spec/genesis_ruby/api/requests/non_financial/payee/account/reverify_spec.rb`
+
+Follows the same structure as the existing Account specs (Retrieve, Create, Update) — config setup, sample data with `Faker::Internet.uuid`, valid/invalid request contexts, and shared example inclusion.
+
+## Data Models
+
+No new data models are introduced. The request uses two string attributes (`payee_unique_id`, `account_unique_id`) and produces an empty JSON body.
+
+**Request body:**
+
+```json
+{}
+```
+
+**Key design decision:** The `request_structure` returns `{}` (empty hash), consistent with the PHP SDK implementation. The reverify endpoint does not require any body parameters — the payee and account identifiers are conveyed entirely through the URL path.
+
+## Correctness Properties
+
+*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
+
+### Property 1: URL path substitution preserves identifiers
+
+*For any* pair of valid `payee_unique_id` and `account_unique_id` strings, building the request document SHALL produce an endpoint URL that contains both identifiers in the correct path positions: `/payee/{payee_unique_id}/account/{account_unique_id}/reverify`.
+
+**Validates: Requirements 3.2, 3.3, 3.4**
+
+## Error Handling
+
+Error handling is delegated entirely to the existing `Base::Versioned` → `Request` validation framework:
+
+| Condition | Error | Mechanism |
+|---|---|---|
+| `payee_unique_id` is nil or empty | `GenesisRuby::ParameterError` | `required_fields` validation in `check_requirements` |
+| `account_unique_id` is nil or empty | `GenesisRuby::ParameterError` | `required_fields` validation in `check_requirements` |
+| Configuration endpoint not set | `GenesisRuby::EndpointNotSetError` | `build_request_url` in base `Request` |
+| Invalid API version | `GenesisRuby::InvalidArgumentError` | `version=` setter in `Base::Versioned` |
+
+No custom error handling is needed in the Reverify class.
+
+## Testing Strategy
+
+### Dual Testing Approach
+
+**Unit tests (example-based):** Verify specific behaviors with concrete values — JSON body content, HTTP method, endpoint URL format, required field validation errors, and shared example compliance.
+
+**Property tests:** Verify the URL path substitution property across many randomly generated identifier pairs.
+
+### Unit Test Plan
+
+Located at `spec/genesis_ruby/api/requests/non_financial/payee/account/reverify_spec.rb`:
+
+1. **JSON body** — build document and verify `JSON.parse` output equals `{}`
+2. **Endpoint URL** — build document and verify `api_config['url']` matches expected pattern with substituted UUIDs
+3. **HTTP method** — verify `api_config['type']` equals `'POST'`
+4. **Happy path** — `build_document` with all fields does not raise
+5. **Nil payee_unique_id** — raises `GenesisRuby::ParameterError`
+6. **Empty payee_unique_id** — raises `GenesisRuby::ParameterError`
+7. **Nil account_unique_id** — raises `GenesisRuby::ParameterError`
+8. **Empty account_unique_id** — raises `GenesisRuby::ParameterError`
+9. **Shared examples** — `base request examples`, `versioned request examples`
+
+### Property Test Plan
+
+**Library:** `rspec-propcheck` or equivalent Ruby PBT library (e.g., using `Faker` for randomized UUID generation across 100+ iterations).
+
+**Property 1 test:** Generate random UUID pairs, set them on the request, build the document, and assert the resulting URL contains both UUIDs at the correct path positions ending with `/reverify`.
+
+- Minimum 100 iterations
+- Tag: `Feature: payee-reverify-account, Property 1: URL path substitution preserves identifiers`

data/.kiro/specs/f2025112603-add_reverify_endpoint_to_payee_account/requirements.md

@@ -0,0 +1,81 @@
+# Requirements Document
+
+## Introduction
+
+Add a "Reverify Payee Account" endpoint to the genesis_ruby SDK. This endpoint allows retrying failed Account verifications by sending a POST request to `/payee/:payee_unique_id/account/:account_unique_id/reverify`. The implementation follows the existing Payee Account request patterns (Create, Retrieve, Update, List) in the SDK.
+
+## Glossary
+
+- **SDK**: The genesis_ruby Ruby gem that provides a client library for the Genesis Payment Processing Gateway.
+- **Reverify_Request**: The new `GenesisRuby::Api::Requests::NonFinancial::Payee::Account::Reverify` class that sends a POST request to reverify a Payee Account.
+- **Payee**: An entity in the Genesis Payment Gateway identified by a `payee_unique_id`.
+- **Account**: A financial account belonging to a Payee, identified by an `account_unique_id`.
+- **Base_Versioned**: The `GenesisRuby::Api::Requests::Base::Versioned` abstract base class for versioned JSON API requests.
+- **Request_Path**: The URL path template used by the request, with placeholder tokens for dynamic identifiers.
+- **Request_Structure**: The Ruby hash that defines the JSON body of the request.
+- **Field_Validations**: The set of required field and value constraints enforced before a request is sent.
+
+## Requirements
+
+### Requirement 1: Reverify Request Class
+
+**User Story:** As a developer integrating with the Genesis Payment Gateway, I want a Reverify request class for Payee Accounts, so that I can retry failed account verifications through the SDK.
+
+#### Acceptance Criteria
+
+1. THE Reverify_Request SHALL inherit from Base_Versioned.
+2. THE Reverify_Request SHALL be defined in the `GenesisRuby::Api::Requests::NonFinancial::Payee::Account` module.
+3. THE Reverify_Request SHALL be located at `lib/genesis_ruby/api/requests/non_financial/payee/account/reverify.rb`.
+4. THE Reverify_Request SHALL be auto-loaded by the existing glob pattern in `dependencies.rb` without manual require statements.
+
+### Requirement 2: Request Parameters
+
+**User Story:** As a developer, I want to specify the Payee and Account identifiers for the reverify request, so that the correct account verification is retried.
+
+#### Acceptance Criteria
+
+1. THE Reverify_Request SHALL expose a `payee_unique_id` attribute via `attr_accessor`.
+2. THE Reverify_Request SHALL expose an `account_unique_id` attribute via `attr_accessor`.
+3. WHEN `payee_unique_id` is nil or empty, THE Reverify_Request SHALL raise a `GenesisRuby::ParameterError`.
+4. WHEN `account_unique_id` is nil or empty, THE Reverify_Request SHALL raise a `GenesisRuby::ParameterError`.
+
+### Requirement 3: HTTP Endpoint Configuration
+
+**User Story:** As a developer, I want the reverify request to target the correct API endpoint, so that the Gateway processes the reverification.
+
+#### Acceptance Criteria
+
+1. THE Reverify_Request SHALL use the POST HTTP method.
+2. THE Reverify_Request SHALL set the Request_Path to `payee/:payee_unique_id/account/:account_unique_id/reverify`.
+3. WHEN `process_request_parameters` is called, THE Reverify_Request SHALL substitute `:payee_unique_id` in the Request_Path with the value of the `payee_unique_id` attribute.
+4. WHEN `process_request_parameters` is called, THE Reverify_Request SHALL substitute `:account_unique_id` in the Request_Path with the value of the `account_unique_id` attribute.
+5. WHEN `process_request_parameters` is called, THE Reverify_Request SHALL invoke `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 4: Request Body Structure
+
+**User Story:** As a developer, I want the reverify request to send an empty JSON body, so that the Gateway accepts the reverification request.
+
+#### Acceptance Criteria
+
+1. THE Reverify_Request SHALL define a `request_structure` method that returns an empty hash `{}`.
+2. WHEN the request document is built, THE Reverify_Request SHALL produce an empty JSON body `{}`.
+
+### Requirement 5: RSpec Test Coverage
+
+**User Story:** As a developer, I want comprehensive tests for the Reverify request, so that the implementation is verified against the expected behavior.
+
+#### Acceptance Criteria
+
+1. THE test file SHALL be located at `spec/genesis_ruby/api/requests/non_financial/payee/account/reverify_spec.rb`.
+2. THE test file SHALL start with the `# frozen_string_literal: true` comment.
+3. THE test suite SHALL verify that the built document produces an empty JSON body `{}`.
+4. THE test suite SHALL verify that the endpoint URL resolves to `https://staging.api.emerchantpay.net:443/payee/{payee_unique_id}/account/{account_unique_id}/reverify`.
+5. THE test suite SHALL verify that the HTTP method is POST.
+6. THE test suite SHALL verify that building the document with all required fields does not raise an error.
+7. THE test suite SHALL verify that a nil `payee_unique_id` raises a `GenesisRuby::ParameterError`.
+8. THE test suite SHALL verify that an empty `payee_unique_id` raises a `GenesisRuby::ParameterError`.
+9. THE test suite SHALL verify that a nil `account_unique_id` raises a `GenesisRuby::ParameterError`.
+10. THE test suite SHALL verify that an empty `account_unique_id` raises a `GenesisRuby::ParameterError`.
+11. THE test suite SHALL include the `base request examples` shared example group.
+12. THE test suite SHALL include the `versioned request examples` shared example group.
+13. THE test suite SHALL use `to_not` (not `not_to`) per the RuboCop configuration.

data/.kiro/specs/f2025112603-add_reverify_endpoint_to_payee_account/tasks.md

@@ -0,0 +1,48 @@
+# Implementation Plan: Reverify Payee Account
+
+## Overview
+
+Implement the `Reverify` request class for the Payee Account module following the established patterns of sibling classes (Create, Retrieve, Update). The class inherits from `Base::Versioned`, uses POST, sends an empty JSON body `{}`, and substitutes path tokens for `payee_unique_id` and `account_unique_id`. Auto-loading via the existing glob in `dependencies.rb` means no manual require is needed.
+
+## Tasks
+
+- [x] 1. Create the Reverify request class
+  - [x] 1.1 Create `lib/genesis_ruby/api/requests/non_financial/payee/account/reverify.rb`
+    - Define `GenesisRuby::Api::Requests::NonFinancial::Payee::Account::Reverify` inheriting from `Base::Versioned`
+    - Add `attr_accessor :payee_unique_id, :account_unique_id`
+    - In `initialize`, call `super configuration` and set `self.request_path = 'payee/:payee_unique_id/account/:account_unique_id/reverify'`
+    - Implement `init_field_validations` pushing `payee_unique_id` and `account_unique_id` onto `required_fields`
+    - Implement `request_structure` returning `{}`
+    - Implement `process_request_parameters` substituting both path tokens via `gsub` and calling `init_api_service_configuration` with `include_token: false`
+    - _Requirements: 1.1, 1.2, 1.3, 1.4, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2, 3.3, 3.4, 3.5, 4.1, 4.2_
+
+- [x] 2. Create the RSpec test suite
+  - [x] 2.1 Create `spec/genesis_ruby/api/requests/non_financial/payee/account/reverify_spec.rb`
+    - Set up `config`, `sample_data` (using `Faker::Internet.uuid`), and `request` let blocks following the Retrieve spec pattern
+    - Define `test_required_fields` as `%i[payee_unique_id account_unique_id]`
+    - Test that built document JSON equals `{}`
+    - Test that endpoint URL resolves to `https://staging.api.emerchantpay.net:443/payee/{payee_unique_id}/account/{account_unique_id}/reverify`
+    - Test that HTTP method is `POST`
+    - Test that `build_document` with all fields does not raise
+    - Test that nil `payee_unique_id` raises `GenesisRuby::ParameterError`
+    - Test that empty `payee_unique_id` raises `GenesisRuby::ParameterError`
+    - Test that nil `account_unique_id` raises `GenesisRuby::ParameterError`
+    - Test that empty `account_unique_id` raises `GenesisRuby::ParameterError`
+    - Include `base request examples` and `versioned request examples` shared example groups
+    - Use `to_not` (not `not_to`) per RuboCop configuration
+    - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 5.9, 5.10, 5.11, 5.12, 5.13_
+
+  - [x] 2.2 Write property test for URL path substitution
+    - **Property 1: URL path substitution preserves identifiers**
+    - Generate 100+ random UUID pairs using `Faker::Internet.uuid`, set them on the request, build the document, and assert the resulting URL contains both UUIDs at the correct path positions ending with `/reverify`
+    - **Validates: Requirements 3.2, 3.3, 3.4**
+
+- [x] 3. Checkpoint — Verify implementation
+  - Ensure all tests pass, ask the user if questions arise.
+
+## Notes
+
+- Tasks marked with `*` are optional and can be skipped for faster MVP
+- Each task references specific requirements for traceability
+- The file is auto-loaded by the glob pattern in `dependencies.rb` — no manual require needed
+- Property test validates the URL path substitution correctness property from the design

data/.kiro/specs/f2025112606-add_list_payees_trx_request/.config.kiro

@@ -0,0 +1 @@
+{"specId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "workflowType": "requirements-first", "specType": "feature"}

data/.kiro/specs/f2025112606-add_list_payees_trx_request/design.md

@@ -0,0 +1,112 @@
+# Design Document
+
+## Overview
+
+This design adds a `List` request class to the `GenesisRuby::Api::Requests::NonFinancial::Payee` module. The class sends a `GET` request to `/payee` with an empty JSON body `{}`, allowing SDK consumers to retrieve the details of all Payees.
+
+The implementation follows the established patterns of the existing Payee request classes (Create, Retrieve, Update) — inheriting from `Base::Versioned`, using the JSON builder, and configuring the API service endpoint without a terminal token. This is the simplest Payee request since it has no required fields and no path token substitution.
+
+## Architecture
+
+The List class slots into the existing request hierarchy with no new abstractions:
+
+```mermaid
+classDiagram
+    class Request {
+        <<abstract>>
+        #init_configuration()
+        #process_request_parameters()
+        #init_api_service_configuration()
+        +build_document()
+    }
+    class Versioned {
+        <<abstract>>
+        #request_path
+        #request_structure()
+        #init_json_configuration()
+    }
+    class List {
+        #init_configuration()
+        #request_structure()
+        #process_request_parameters()
+    }
+
+    Request <|-- Versioned
+    Versioned <|-- List
+```
+
+The class overrides `init_configuration` to call `init_get_configuration` (switching from the default POST to GET), matching the pattern used by `Payee::Retrieve` and `Payee::Account::List`.
+
+## Components and Interfaces
+
+### New File
+
+`lib/genesis_ruby/api/requests/non_financial/payee/list.rb`
+
+### Class: `GenesisRuby::Api::Requests::NonFinancial::Payee::List`
+
+**Superclass:** `GenesisRuby::Api::Requests::Base::Versioned`
+
+**Public interface:**
+
+| Member | Type | Description |
+|---|---|---|
+| `initialize(configuration, _builder_interface = nil)` | constructor | Sets `request_path` to `payee` |
+
+**Protected methods:**
+
+| Method | Description |
+|---|---|
+| `init_configuration` | Calls `super`, then `init_get_configuration` to switch to GET |
+| `request_structure` | Returns `{}` (empty hash) |
+| `process_request_parameters` | Calls `init_api_service_configuration` with `request_path` and `include_token: false`, then `super` |
+
+### Auto-loading
+
+The file path `lib/genesis_ruby/api/requests/non_financial/payee/list.rb` matches the existing glob in `dependencies.rb`:
+
+```ruby
+Dir["#{File.dirname(__FILE__)}/api/requests/*financial/**/*.rb"].sort.each { |file| require file }
+```
+
+No changes to `dependencies.rb` are needed.
+
+### New Test File
+
+`spec/genesis_ruby/api/requests/non_financial/payee/list_spec.rb`
+
+Follows the same structure as the existing Payee::Retrieve spec — config setup, request let block, and shared example inclusion. Simpler than Retrieve since there are no required fields or path token substitution.
+
+## Data Models
+
+No new data models are introduced. The request has no attributes and produces an empty JSON body.
+
+**Request body:**
+
+```json
+{}
+```
+
+## Error Handling
+
+Error handling is delegated entirely to the existing `Base::Versioned` → `Request` validation framework:
+
+| Condition | Error | Mechanism |
+|---|---|---|
+| Configuration endpoint not set | `GenesisRuby::EndpointNotSetError` | `build_request_url` in base `Request` |
+| Invalid API version | `GenesisRuby::InvalidArgumentError` | `version=` setter in `Base::Versioned` |
+
+No custom error handling is needed in the List class. There are no required fields to validate.
+
+## Testing Strategy
+
+### Unit Test Plan
+
+Located at `spec/genesis_ruby/api/requests/non_financial/payee/list_spec.rb`:
+
+1. **JSON body** — build document and verify `JSON.parse` output equals `{}`
+2. **Endpoint URL** — build document and verify `api_config['url']` equals `https://staging.api.emerchantpay.net:443/payee`
+3. **HTTP method** — verify `api_config['type']` equals `'GET'`
+4. **Token exclusion** — verify `api_config['token']` is nil
+5. **Happy path** — `build_document` without any attributes does not raise
+6. **Shared examples** — `base request examples`, `versioned request examples`

data/.kiro/specs/f2025112606-add_list_payees_trx_request/requirements.md

@@ -0,0 +1,74 @@
+# Requirements Document
+
+## Introduction
+
+Add a "List Payees" endpoint to the genesis_ruby SDK. This endpoint retrieves the details of all Payees by sending a GET request to `/payee`. The implementation follows the existing Payee request patterns (Create, Retrieve, Update) in the SDK.
+
+API Reference: [Payee API — List Payees](https://emerchantpay.github.io/gateway-api-docs/#payee-api-list-payees)
+
+## Glossary
+
+- **SDK**: The genesis_ruby Ruby gem that provides a client library for the Genesis Payment Processing Gateway.
+- **List_Request**: The new `GenesisRuby::Api::Requests::NonFinancial::Payee::List` class that sends a GET request to list all Payees.
+- **Payee**: An entity in the Genesis Payment Gateway identified by a `unique_id`.
+- **Base_Versioned**: The `GenesisRuby::Api::Requests::Base::Versioned` abstract base class for versioned JSON API requests.
+- **Request_Path**: The URL path used by the request.
+- **Request_Structure**: The Ruby hash that defines the JSON body of the request.
+
+## Requirements
+
+### Requirement 1: List Payees Request Class
+
+**User Story:** As a developer integrating with the Genesis Payment Gateway, I want a List Payees request class, so that I can retrieve the details of all Payees through the SDK.
+
+#### Acceptance Criteria
+
+1. THE List_Request SHALL inherit from Base_Versioned.
+2. THE List_Request SHALL be defined in the `GenesisRuby::Api::Requests::NonFinancial::Payee` module.
+3. THE List_Request SHALL be located at `lib/genesis_ruby/api/requests/non_financial/payee/list.rb`.
+4. THE List_Request SHALL be auto-loaded by the existing glob pattern in `dependencies.rb` without manual require statements.
+
+### Requirement 2: HTTP Endpoint Configuration
+
+**User Story:** As a developer, I want the list payees request to target the correct API endpoint, so that the Gateway returns all Payee records.
+
+#### Acceptance Criteria
+
+1. THE List_Request SHALL use the GET HTTP method.
+2. THE List_Request SHALL set the Request_Path to `payee`.
+3. WHEN `process_request_parameters` is called, THE List_Request SHALL invoke `init_api_service_configuration` with `request_path: request_path` and `include_token: false`.
+
+### Requirement 3: Request Body Structure
+
+**User Story:** As a developer, I want the list payees request to send an empty JSON body, so that the Gateway accepts the request.
+
+#### Acceptance Criteria
+
+1. THE List_Request SHALL define a `request_structure` method that returns an empty hash `{}`.
+2. WHEN the request document is built, THE List_Request SHALL produce an empty JSON body `{}`.
+
+### Requirement 4: No Required Fields
+
+**User Story:** As a developer, I want the list payees request to work without any required parameters, since the endpoint lists all payees without filters.
+
+#### Acceptance Criteria
+
+1. THE List_Request SHALL NOT define any required fields.
+2. WHEN `build_document` is called without setting any attributes, THE List_Request SHALL NOT raise an error.
+
+### Requirement 5: RSpec Test Coverage
+
+**User Story:** As a developer, I want comprehensive tests for the List Payees request, so that the implementation is verified against the expected behavior.
+
+#### Acceptance Criteria
+
+1. THE test file SHALL be located at `spec/genesis_ruby/api/requests/non_financial/payee/list_spec.rb`.
+2. THE test file SHALL start with the `# frozen_string_literal: true` comment.
+3. THE test suite SHALL verify that the built document produces an empty JSON body `{}`.
+4. THE test suite SHALL verify that the endpoint URL resolves to `https://staging.api.emerchantpay.net:443/payee`.
+5. THE test suite SHALL verify that the HTTP method is GET.
+6. THE test suite SHALL verify that the token is not included in the configuration.
+7. THE test suite SHALL verify that building the document without any attributes does not raise an error.
+8. THE test suite SHALL include the `base request examples` shared example group.
+9. THE test suite SHALL include the `versioned request examples` shared example group.
+10. THE test suite SHALL use `to_not` (not `not_to`) per the RuboCop configuration.

data/.kiro/specs/f2025112606-add_list_payees_trx_request/tasks.md

@@ -0,0 +1,38 @@
+# Implementation Plan: List Payees
+
+## Overview
+
+Implement the `List` request class for the Payee module following the established patterns of sibling classes (Create, Retrieve, Update). The class inherits from `Base::Versioned`, uses GET, sends an empty JSON body `{}`, and targets the `/payee` endpoint. Auto-loading via the existing glob in `dependencies.rb` means no manual require is needed.
+
+## Tasks
+
+- [x] 1. Create the List Payees request class
+  - [x] 1.1 Create `lib/genesis_ruby/api/requests/non_financial/payee/list.rb`
+    - Define `GenesisRuby::Api::Requests::NonFinancial::Payee::List` inheriting from `Base::Versioned`
+    - In `initialize`, call `super configuration` and set `self.request_path = 'payee'`
+    - Override `init_configuration` to call `super` then `init_get_configuration`
+    - Implement `request_structure` returning `{}`
+    - Implement `process_request_parameters` calling `init_api_service_configuration` with `request_path: request_path` and `include_token: false`, then `super`
+    - _Requirements: 1.1, 1.2, 1.3, 1.4, 2.1, 2.2, 2.3, 3.1, 3.2, 4.1, 4.2_
+
+- [x] 2. Create the RSpec test suite
+  - [x] 2.1 Create `spec/genesis_ruby/api/requests/non_financial/payee/list_spec.rb`
+    - Set up `config` and `request` let blocks following the Retrieve spec pattern
+    - Test that built document JSON equals `{}`
+    - Test that endpoint URL resolves to `https://staging.api.emerchantpay.net:443/payee`
+    - Test that HTTP method is `GET`
+    - Test that token is not included in configuration
+    - Test that `build_document` without any attributes does not raise
+    - Include `base request examples` and `versioned request examples` shared example groups
+    - Use `to_not` (not `not_to`) per RuboCop configuration
+    - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 5.9, 5.10_
+
+- [x] 3. Checkpoint — Verify implementation
+  - Run `bundle exec rspec spec/genesis_ruby/api/requests/non_financial/payee/list_spec.rb` and ensure all tests pass
+  - Run `bundle exec rubocop lib/genesis_ruby/api/requests/non_financial/payee/list.rb spec/genesis_ruby/api/requests/non_financial/payee/list_spec.rb` and ensure no offenses
+
+## Notes
+
+- Each task references specific requirements for traceability
+- The file is auto-loaded by the glob pattern in `dependencies.rb` — no manual require needed
+- This is the simplest Payee request — no required fields, no path token substitution, no query parameters

data/.kiro/specs/f2025112609_update_payee_request_params/design.md

@@ -0,0 +1,86 @@
+# Design Document
+
+## Overview
+
+Extend the existing `Payee::Create` and `Payee::Update` request classes with additional accessors and a nested address structure, following the established SDK patterns.
+
+## Architecture
+
+### Approach
+
+The implementation adds new `attr_accessor` fields to the existing classes and introduces a private `payee_address_structure` method that builds the nested address hash. The SDK's existing `deep_compact!` mechanism automatically removes nil values and empty hashes, ensuring the `address` key is omitted when all address fields are nil.
+
+### Files Modified
+
+| File | Change |
+|---|---|
+| `lib/genesis_ruby/api/requests/non_financial/payee/create.rb` | Add accessors, address validation, nested structure |
+| `lib/genesis_ruby/api/requests/non_financial/payee/update.rb` | Add accessors, address validation, nested structure |
+| `spec/genesis_ruby/api/requests/non_financial/payee/create_spec.rb` | Add tests for new fields |
+| `spec/genesis_ruby/api/requests/non_financial/payee/update_spec.rb` | Add tests for new fields |
+
+### Design Decisions
+
+1. **Prefixed accessors** (`payee_address_city` instead of `address_city`) — consistent with existing naming in the SDK (e.g., `payee_name`, `payee_country`, `payee_account_type`)
+
+2. **Private helper method** (`payee_address_structure`) — keeps `request_structure` clean and isolates the nested hash construction
+
+3. **Optional address validation** — `payee_address_country` is added to `field_values` for ISO validation but is not in `required_fields`, so it's only validated when set (non-nil)
+
+4. **No mixin** — the address structure is specific to Payee requests and simple enough not to warrant a shared mixin. The existing `AddressInfoAttributes` mixin is designed for billing/shipping addresses with different field names.
+
+5. **deep_compact! handles nil removal** — no custom logic needed; when all address fields are nil, the hash becomes `{}` after compaction, and empty hashes are then removed from the parent
+
+## Expected JSON Payloads
+
+### Payee Create (full)
+```json
+{
+  "payee": {
+    "type": "company",
+    "name": "Office LTD",
+    "country": "GB",
+    "date": "1990-01-01",
+    "notification_url": "https://example.com/notifications",
+    "registration_number": "123456789",
+    "address": {
+      "city": "London",
+      "street": "Test 12",
+      "state": "London",
+      "country": "GB",
+      "zip_code": "1234"
+    }
+  }
+}
+```
+
+### Payee Update (full)
+```json
+{
+  "payee": {
+    "name": "Office LTD",
+    "country": "GB",
+    "date": "1990-01-01",
+    "notification_url": "https://example.com/notifications",
+    "registration_number": "123456789",
+    "address": {
+      "city": "London",
+      "street": "Test 12",
+      "state": "London",
+      "country": "GB",
+      "zip_code": "1234"
+    }
+  }
+}
+```
+
+### Payee Create (minimal — no address)
+```json
+{
+  "payee": {
+    "type": "company",
+    "name": "Office LTD",
+    "country": "GB"
+  }
+}
+```