genesis_ruby 0.3.1 → 0.3.2

data/.kiro/specs/f2025112612-add_payee_owner_documents_and_verification_requests/requirements.md

@@ -0,0 +1,287 @@
+# Requirements Document
+
+## Introduction
+
+Extend the genesis_ruby SDK with missing Payee API request classes for Owner management, Document management, and Verification management. These 20 new non-financial request classes follow the established patterns of the existing Payee and Payee Account request classes, inheriting from `Base::Versioned` and using JSON request/response format against the emerchantpay Versioned API. Additionally, the SDK must be extended with HTTP DELETE method support since the existing codebase only supports POST, GET, PUT, and PATCH.
+
+## Glossary
+
+- **SDK**: The genesis_ruby Ruby gem that wraps the emerchantpay payment gateway API
+- **Versioned_API**: The emerchantpay API service accessed via `staging.api.emerchantpay.net` using versioned paths (e.g., `/v1/...`)
+- **Request_Class**: A Ruby class inheriting from `Base::Versioned` that encapsulates a single API endpoint call
+- **Payee**: A merchant entity registered in the emerchantpay system, identified by `payee_unique_id`
+- **Owner**: An entity (company, person, director, or ultimate beneficial owner) associated with a Payee, identified by `owner_unique_id`
+- **Owner_Type**: One of: `company`, `person`, `director`, `ultimate_beneficial_owner`
+- **Document**: A file (encoded in base64) associated with a Payee or Owner, identified by `document_unique_id`
+- **Document_Type**: The classification of a document, one of: `poi`, `passport`, `id_card`, `driving_license`, `poa`, `utility_bill`, `bank_statement`, `company_registration`, `tax_return`, `memorandum_of_association`, `shareholder_register`, `board_resolution`, `proof_of_address`
+- **Verification**: A KYC verification process for a Payee, identified by `verification_unique_id`
+- **Field_Validation**: The mechanism using `required_fields`, `field_values`, and `field_value_dependencies` to enforce parameter constraints before sending a request
+- **Path_Placeholder**: A token in the request path (e.g., `:payee_unique_id`) that is replaced with the actual value during `process_request_parameters`
+- **Query_Parameter**: An optional filter appended to the URL as a query string for GET list endpoints
+- **Delete_Configuration**: A new HTTP method configuration pattern for DELETE requests, analogous to `init_get_configuration` and `init_patch_configuration`
+
+## Requirements
+
+### Requirement 1: HTTP DELETE Method Support
+
+**User Story:** As a developer using the SDK, I want the SDK to support HTTP DELETE requests, so that I can call API endpoints that require the DELETE method.
+
+#### Acceptance Criteria
+
+1. THE SDK SHALL define a `METHOD_DELETE` constant with value `'DELETE'` in the `Api::Request` class.
+2. THE SDK SHALL provide a `load_delete_config` method in `Utils::Options::ApiConfig` that configures the request type to `METHOD_DELETE`, format to `Builder::JSON`, and authorization to `AUTH_TYPE_BASIC`.
+3. THE SDK SHALL provide an `init_delete_configuration` method in `Api::Request` that calls `@api_config.load_delete_config`.
+4. THE SDK SHALL handle the DELETE format in `NetworkAdapterConfig#fetch_content_type` returning `'application/json'`.
+
+### Requirement 2: List Payee Owners
+
+**User Story:** As a developer, I want to list all owners associated with a specific payee, so that I can retrieve ownership information.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/:payee_unique_id/owners'`.
+2. THE Request_Class SHALL use GET HTTP method via `init_get_configuration`.
+3. THE Request_Class SHALL require `payee_unique_id` as a required field.
+4. WHEN an optional `type` query parameter is provided, THE Request_Class SHALL append it to the URL as a query string.
+5. THE Request_Class SHALL return an empty request structure.
+6. THE Request_Class SHALL replace the `:payee_unique_id` placeholder and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 3: Associate Payee with Owners
+
+**User Story:** As a developer, I want to associate owners with a payee, so that I can establish ownership relationships.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/:payee_unique_id/owners'`.
+2. THE Request_Class SHALL use POST HTTP method (default).
+3. THE Request_Class SHALL require `payee_unique_id` as a required field.
+4. THE Request_Class SHALL accept an `owners` array parameter where each element contains `unique_id` and `percent_ownership`.
+5. THE Request_Class SHALL return a request structure containing the `owners` array.
+6. THE Request_Class SHALL replace the `:payee_unique_id` placeholder and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 4: Dissociate Payee from Owners
+
+**User Story:** As a developer, I want to dissociate owners from a payee, so that I can remove ownership relationships.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/:payee_unique_id/owners'`.
+2. THE Request_Class SHALL use DELETE HTTP method via `init_delete_configuration`.
+3. THE Request_Class SHALL require `payee_unique_id` as a required field.
+4. THE Request_Class SHALL accept an `owners` array parameter containing owner `unique_id` values.
+5. THE Request_Class SHALL return a request structure containing the `owners` array.
+6. THE Request_Class SHALL replace the `:payee_unique_id` placeholder and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 5: Create Payee Document
+
+**User Story:** As a developer, I want to create a document for a payee, so that I can upload verification documents.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/:payee_unique_id/documents'`.
+2. THE Request_Class SHALL use POST HTTP method (default).
+3. THE Request_Class SHALL require `payee_unique_id`, `document_type`, and `file` as required fields.
+4. THE Request_Class SHALL validate `document_type` against the allowed Document_Type values.
+5. THE Request_Class SHALL return a request structure containing `document_type` and `file` (base64 encoded) nested under a `document` key.
+6. THE Request_Class SHALL replace the `:payee_unique_id` placeholder and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 6: Retrieve Payee Document
+
+**User Story:** As a developer, I want to retrieve a specific document for a payee, so that I can access uploaded document details.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/:payee_unique_id/documents/:document_unique_id'`.
+2. THE Request_Class SHALL use GET HTTP method via `init_get_configuration`.
+3. THE Request_Class SHALL require `payee_unique_id` and `document_unique_id` as required fields.
+4. THE Request_Class SHALL return an empty request structure.
+5. THE Request_Class SHALL replace both `:payee_unique_id` and `:document_unique_id` placeholders and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 7: List Payee Documents
+
+**User Story:** As a developer, I want to list all documents for a payee, so that I can view all uploaded documents.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/:payee_unique_id/documents'`.
+2. THE Request_Class SHALL use GET HTTP method via `init_get_configuration`.
+3. THE Request_Class SHALL require `payee_unique_id` as a required field.
+4. THE Request_Class SHALL return an empty request structure.
+5. THE Request_Class SHALL replace the `:payee_unique_id` placeholder and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 8: Create Payee Verification
+
+**User Story:** As a developer, I want to create a verification for a payee, so that I can initiate the KYC verification process.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/:payee_unique_id/verifications'`.
+2. THE Request_Class SHALL use POST HTTP method (default).
+3. THE Request_Class SHALL require `payee_unique_id` as a required field.
+4. THE Request_Class SHALL accept optional `notification_url`, `redirect_url`, and `with_checks_retry` parameters.
+5. THE Request_Class SHALL return a request structure containing `notification_url`, `redirect_url`, and `with_checks_retry` nested under a `verification` key.
+6. THE Request_Class SHALL replace the `:payee_unique_id` placeholder and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 9: Retrieve Payee Verification
+
+**User Story:** As a developer, I want to retrieve a specific verification for a payee, so that I can check verification status.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/:payee_unique_id/verifications/:verification_unique_id'`.
+2. THE Request_Class SHALL use GET HTTP method via `init_get_configuration`.
+3. THE Request_Class SHALL require `payee_unique_id` and `verification_unique_id` as required fields.
+4. THE Request_Class SHALL return an empty request structure.
+5. THE Request_Class SHALL replace both `:payee_unique_id` and `:verification_unique_id` placeholders and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 10: List Payee Verifications
+
+**User Story:** As a developer, I want to list all verifications for a payee, so that I can view the verification history.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/:payee_unique_id/verifications'`.
+2. THE Request_Class SHALL use GET HTTP method via `init_get_configuration`.
+3. THE Request_Class SHALL require `payee_unique_id` as a required field.
+4. THE Request_Class SHALL return an empty request structure.
+5. THE Request_Class SHALL replace the `:payee_unique_id` placeholder and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 11: Create Owner
+
+**User Story:** As a developer, I want to create an owner entity, so that I can register companies, persons, directors, or ultimate beneficial owners.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/owners'`.
+2. THE Request_Class SHALL use POST HTTP method (default).
+3. THE Request_Class SHALL require `owner_type`, `owner_name`, and `owner_country` as required fields.
+4. THE Request_Class SHALL validate `owner_type` against the allowed Owner_Type values (`company`, `person`, `director`, `ultimate_beneficial_owner`).
+5. THE Request_Class SHALL validate `owner_country` against `GenesisRuby::Utils::Country::COUNTRIES.keys`.
+6. THE Request_Class SHALL accept optional parameters: `owner_date`, `notification_url`, `registration_number`, `owner_address` (hash with `first_line`, `second_line`, `city`, `zip_code`, `state`), `payees` array, and `owners` array.
+7. THE Request_Class SHALL return a request structure containing all owner fields nested under an `owner` key.
+8. THE Request_Class SHALL call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 12: Retrieve Owner
+
+**User Story:** As a developer, I want to retrieve a specific owner, so that I can access owner details.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/owners/:owner_unique_id'`.
+2. THE Request_Class SHALL use GET HTTP method via `init_get_configuration`.
+3. THE Request_Class SHALL require `owner_unique_id` as a required field.
+4. THE Request_Class SHALL return an empty request structure.
+5. THE Request_Class SHALL replace the `:owner_unique_id` placeholder and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 13: Update Owner
+
+**User Story:** As a developer, I want to update an existing owner, so that I can modify owner details.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/owners/:owner_unique_id'`.
+2. THE Request_Class SHALL use PATCH HTTP method via `init_patch_configuration`.
+3. THE Request_Class SHALL require `owner_unique_id` as a required field.
+4. THE Request_Class SHALL accept optional parameters: `owner_name`, `owner_country`, `owner_date`, `notification_url`, `registration_number`, and `owner_address`.
+5. THE Request_Class SHALL validate `owner_country` against `GenesisRuby::Utils::Country::COUNTRIES.keys` when provided.
+6. THE Request_Class SHALL return a request structure containing the updatable fields nested under an `owner` key.
+7. THE Request_Class SHALL replace the `:owner_unique_id` placeholder and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 14: Delete Owner
+
+**User Story:** As a developer, I want to delete an owner, so that I can remove owner entities from the system.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/owners/:owner_unique_id'`.
+2. THE Request_Class SHALL use DELETE HTTP method via `init_delete_configuration`.
+3. THE Request_Class SHALL require `owner_unique_id` as a required field.
+4. THE Request_Class SHALL return an empty request structure.
+5. THE Request_Class SHALL replace the `:owner_unique_id` placeholder and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 15: List Owners
+
+**User Story:** As a developer, I want to list all owners, so that I can retrieve all registered owner entities.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/owners'`.
+2. THE Request_Class SHALL use GET HTTP method via `init_get_configuration`.
+3. THE Request_Class SHALL return an empty request structure.
+4. THE Request_Class SHALL call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 16: Associate Owner with Owners
+
+**User Story:** As a developer, I want to associate owners with another owner, so that I can establish nested ownership hierarchies.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/owners/:owner_unique_id/owners'`.
+2. THE Request_Class SHALL use POST HTTP method (default).
+3. THE Request_Class SHALL require `owner_unique_id` as a required field.
+4. THE Request_Class SHALL accept an `owners` array parameter where each element contains `unique_id` and `percent_ownership`.
+5. THE Request_Class SHALL return a request structure containing the `owners` array.
+6. THE Request_Class SHALL replace the `:owner_unique_id` placeholder and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 17: Dissociate Owner from Owners
+
+**User Story:** As a developer, I want to dissociate owners from another owner, so that I can remove nested ownership relationships.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/owners/:owner_unique_id/owners'`.
+2. THE Request_Class SHALL use DELETE HTTP method via `init_delete_configuration`.
+3. THE Request_Class SHALL require `owner_unique_id` as a required field.
+4. THE Request_Class SHALL accept an `owners` array parameter containing owner `unique_id` values.
+5. THE Request_Class SHALL return a request structure containing the `owners` array.
+6. THE Request_Class SHALL replace the `:owner_unique_id` placeholder and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 18: Create Owner Document
+
+**User Story:** As a developer, I want to create a document for an owner, so that I can upload verification documents for owner entities.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/owners/:owner_unique_id/documents'`.
+2. THE Request_Class SHALL use POST HTTP method (default).
+3. THE Request_Class SHALL require `owner_unique_id`, `document_type`, and `file` as required fields.
+4. THE Request_Class SHALL validate `document_type` against the allowed Document_Type values.
+5. THE Request_Class SHALL return a request structure containing `document_type` and `file` (base64 encoded) nested under a `document` key.
+6. THE Request_Class SHALL replace the `:owner_unique_id` placeholder and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 19: Retrieve Owner Document
+
+**User Story:** As a developer, I want to retrieve a specific document for an owner, so that I can access uploaded owner document details.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/owners/:owner_unique_id/documents/:document_unique_id'`.
+2. THE Request_Class SHALL use GET HTTP method via `init_get_configuration`.
+3. THE Request_Class SHALL require `owner_unique_id` and `document_unique_id` as required fields.
+4. THE Request_Class SHALL return an empty request structure.
+5. THE Request_Class SHALL replace both `:owner_unique_id` and `:document_unique_id` placeholders and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 20: List Owner Documents
+
+**User Story:** As a developer, I want to list all documents for an owner, so that I can view all uploaded owner documents.
+
+#### Acceptance Criteria
+
+1. THE Request_Class SHALL inherit from `Base::Versioned` and set `request_path` to `'payee/owners/:owner_unique_id/documents'`.
+2. THE Request_Class SHALL use GET HTTP method via `init_get_configuration`.
+3. THE Request_Class SHALL require `owner_unique_id` as a required field.
+4. THE Request_Class SHALL return an empty request structure.
+5. THE Request_Class SHALL replace the `:owner_unique_id` placeholder and call `init_api_service_configuration` with `include_token: false`.
+
+### Requirement 21: Consistent Pattern Compliance
+
+**User Story:** As a developer, I want all new request classes to follow the established SDK patterns, so that the codebase remains consistent and maintainable.
+
+#### Acceptance Criteria
+
+1. THE SDK SHALL place all new Request_Class files under `lib/genesis_ruby/api/requests/non_financial/payee/` following the directory structure: `owners/`, `documents/`, `verifications/`, `owner/`, `owner/owners/`, `owner/documents/`.
+2. THE SDK SHALL provide a corresponding RSpec test file for each new Request_Class under `spec/genesis_ruby/api/requests/non_financial/payee/` mirroring the source directory structure.
+3. WHEN a Request_Class uses path placeholders, THE Request_Class SHALL replace all placeholders in `process_request_parameters` before calling `init_api_service_configuration`.
+4. THE SDK SHALL include `'base request examples'` and `'versioned request examples'` shared example groups in each new spec file.
+5. WHEN a Request_Class accepts optional query parameters for list endpoints, THE Request_Class SHALL build a query string and append it to the processed path following the `Account::List` pattern.
+6. THE SDK SHALL validate country fields against `GenesisRuby::Utils::Country::COUNTRIES.keys` using `field_values` wherever a country parameter is accepted.

data/.kiro/specs/f2025112612-add_payee_owner_documents_and_verification_requests/tasks.md

@@ -0,0 +1,76 @@
+# Tasks
+
+## Task 1: HTTP DELETE Infrastructure
+
+- [x] 1.1 Add `METHOD_DELETE = 'DELETE'` constant to `lib/genesis_ruby/api/request.rb` after `METHOD_PATCH`
+- [x] 1.2 Add `load_delete_config` method to `lib/genesis_ruby/utils/options/api_config.rb` (type: METHOD_DELETE, format: Builder::JSON, authorization: AUTH_TYPE_BASIC)
+- [x] 1.3 Add `init_delete_configuration` method to `lib/genesis_ruby/api/request.rb` that calls `@api_config.load_delete_config`
+- [x] 1.4 Add DELETE case to `Network::Adapter::NetHttpAdapter#execute` — `when Api::Request::METHOD_DELETE then @response = @request.delete path, headers`
+- [x] 1.5 Update `NetHttpAdapter#headers` to exclude payload headers for DELETE (same as GET)
+- [x] 1.6 Add unit tests for DELETE infrastructure in existing spec files
+
+## Task 2: Constants for Owner Types and Document Types
+
+- [x] 2.1 Create `lib/genesis_ruby/api/constants/non_financial/payee/owner_types.rb` with constants: COMPANY, PERSON, DIRECTOR, ULTIMATE_BENEFICIAL_OWNER
+- [x] 2.2 Create `lib/genesis_ruby/api/constants/non_financial/payee/document_types.rb` with all document type constants
+
+## Task 3: Payee-level Owners Operations (flat in payee/)
+
+- [x] 3.1 Create `lib/genesis_ruby/api/requests/non_financial/payee/list_payee_owners.rb` — GET with optional `type` query param
+- [x] 3.2 Create `lib/genesis_ruby/api/requests/non_financial/payee/associate_payee_with_owners.rb` — POST with `owners` array body
+- [x] 3.3 Create `lib/genesis_ruby/api/requests/non_financial/payee/dissociate_payee_with_owners.rb` — DELETE with `owners` array body
+- [x] 3.4 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/list_payee_owners_spec.rb`
+- [x] 3.5 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/associate_payee_with_owners_spec.rb`
+- [x] 3.6 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/dissociate_payee_with_owners_spec.rb`
+
+## Task 4: Payee-level Documents Operations (flat in payee/)
+
+- [x] 4.1 Create `lib/genesis_ruby/api/requests/non_financial/payee/create_payee_document.rb` — POST with document_type validation and file
+- [x] 4.2 Create `lib/genesis_ruby/api/requests/non_financial/payee/retrieve_payee_document.rb` — GET with payee_unique_id and document_unique_id
+- [x] 4.3 Create `lib/genesis_ruby/api/requests/non_financial/payee/list_payee_documents.rb` — GET with payee_unique_id
+- [x] 4.4 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/create_payee_document_spec.rb`
+- [x] 4.5 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/retrieve_payee_document_spec.rb`
+- [x] 4.6 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/list_payee_documents_spec.rb`
+
+## Task 5: Payee Verifications (in payee/verifications/)
+
+- [x] 5.1 Create `lib/genesis_ruby/api/requests/non_financial/payee/verifications/create_payee_verification.rb` — POST with optional notification_url, redirect_url, with_checks_retry
+- [x] 5.2 Create `lib/genesis_ruby/api/requests/non_financial/payee/verifications/retrieve_payee_verification.rb` — GET with payee_unique_id and verification_unique_id
+- [x] 5.3 Create `lib/genesis_ruby/api/requests/non_financial/payee/verifications/list_payee_verifications.rb` — GET with payee_unique_id
+- [x] 5.4 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/verifications/create_payee_verification_spec.rb`
+- [x] 5.5 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/verifications/retrieve_payee_verification_spec.rb`
+- [x] 5.6 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/verifications/list_payee_verifications_spec.rb`
+
+## Task 6: Owner CRUD (in payee/owners/)
+
+- [x] 6.1 Create `lib/genesis_ruby/api/requests/non_financial/payee/owners/create.rb` — POST with owner_type, owner_name, owner_country validations, optional address/payees/owners
+- [x] 6.2 Create `lib/genesis_ruby/api/requests/non_financial/payee/owners/retrieve.rb` — GET with owner_unique_id
+- [x] 6.3 Create `lib/genesis_ruby/api/requests/non_financial/payee/owners/update.rb` — PATCH with owner_unique_id, optional fields
+- [x] 6.4 Create `lib/genesis_ruby/api/requests/non_financial/payee/owners/delete.rb` — DELETE with owner_unique_id
+- [x] 6.5 Create `lib/genesis_ruby/api/requests/non_financial/payee/owners/list_owners.rb` — GET, no required fields
+- [x] 6.6 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/owners/create_spec.rb`
+- [x] 6.7 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/owners/retrieve_spec.rb`
+- [x] 6.8 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/owners/update_spec.rb`
+- [x] 6.9 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/owners/delete_spec.rb`
+- [x] 6.10 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/owners/list_owners_spec.rb`
+
+## Task 7: Owner sub-operations — Owners Association (in payee/owners/)
+
+- [x] 7.1 Create `lib/genesis_ruby/api/requests/non_financial/payee/owners/associate_owner_with_owners.rb` — POST with owners array
+- [x] 7.2 Create `lib/genesis_ruby/api/requests/non_financial/payee/owners/dissociate_owners.rb` — DELETE with owners array
+- [x] 7.3 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/owners/associate_owner_with_owners_spec.rb`
+- [x] 7.4 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/owners/dissociate_owners_spec.rb`
+
+## Task 8: Owner sub-operations — Documents (in payee/owners/)
+
+- [x] 8.1 Create `lib/genesis_ruby/api/requests/non_financial/payee/owners/create_owner_document.rb` — POST with document_type validation and file
+- [x] 8.2 Create `lib/genesis_ruby/api/requests/non_financial/payee/owners/retrieve_owner_document.rb` — GET with owner_unique_id and document_unique_id
+- [x] 8.3 Create `lib/genesis_ruby/api/requests/non_financial/payee/owners/list_owner_documents.rb` — GET with owner_unique_id
+- [x] 8.4 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/owners/create_owner_document_spec.rb`
+- [x] 8.5 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/owners/retrieve_owner_document_spec.rb`
+- [x] 8.6 Create spec: `spec/genesis_ruby/api/requests/non_financial/payee/owners/list_owner_documents_spec.rb`
+
+## Task 9: Run Full Test Suite
+
+- [x] 9.1 Run `bundle exec rspec` to verify all new and existing tests pass
+- [x] 9.2 Fix any failures or regressions

data/.kiro/specs/f2025112614-add_money_transfer_payout_attributes_to_payout_rq/design.md

@@ -0,0 +1,84 @@
+# Design Document
+
+## Overview
+
+This feature adds Money Transfer Payout attributes to the existing Payout transaction request. It follows the established SDK patterns: constants under `Api::Constants::Transactions::Parameters::MoneyTransfer::`, a mixin module under `Api::Mixins::Requests::Financial::`, and shared RSpec examples for test reuse.
+
+## Architecture
+
+### Constants (new directory: `money_transfer/`)
+
+```
+lib/genesis_ruby/api/constants/transactions/parameters/money_transfer/
+├── types.rb                       # visa, mastercard
+├── sender_account_number_types.rb # iban, credit_debit_card, etc.
+├── purpose_of_payments.rb         # family_support, education, etc.
+└── source_of_funds.rb             # current_account, credit_card, etc.
+```
+
+Each constant class extends `Mixins::Constants::Common` providing `.all` and `.valid?` methods.
+
+### Mixin Module
+
+```
+lib/genesis_ruby/api/mixins/requests/financial/money_transfer_payout_attributes.rb
+```
+
+Pattern follows `FundingAttributes`:
+- `attr_accessor` for plain string fields (no validation needed)
+- `attr_reader` + custom setter with `allowed_options` for enum fields
+- Custom getter/setter for date field using `parse_date`
+- Protected `money_transfer_payout_attributes_structure` method returning the nested hash
+
+### Request Class Integration
+
+The `Payout` class includes the mixin and adds `money_transfer: money_transfer_payout_attributes_structure` to its `payment_transaction_structure` hash.
+
+### XML Structure
+
+```xml
+<money_transfer>
+  <type>mastercard</type>
+  <sender_account_number>123456</sender_account_number>
+  <sender_birth_date>15-06-1990</sender_birth_date>
+  <service_provider_name>Provider</service_provider_name>
+  <sender_account_number_type>iban</sender_account_number_type>
+  <purpose_of_payment>family_support</purpose_of_payment>
+  <source_of_funds>current_account</source_of_funds>
+  <sender_address>
+    <country>US</country>
+    <city>New York</city>
+    <line>123 Main St</line>
+    <state>NY</state>
+    <postal_code>10001</postal_code>
+  </sender_address>
+  <receiver>
+    <first_name>John</first_name>
+    <last_name>Doe</last_name>
+    <country>GB</country>
+    <city>London</city>
+    <line>456 High St</line>
+    <state>LDN</state>
+    <postal_code>EC1A</postal_code>
+    <account_number>987654</account_number>
+    <account_number_type>card</account_number_type>
+  </receiver>
+</money_transfer>
+```
+
+## Validation Strategy
+
+Enum fields use `allowed_options` in the setter (raises `InvalidArgumentError` immediately on invalid assignment). This differs from the `field_values` approach used by `FundingAttributes` (which validates at `build_document` time raising `ParameterError`). The setter-based approach was chosen to match `SourceOfFundsAttributes` and `PurposeOfPaymentAttributes` patterns already used on the same Payout class.
+
+## Test Strategy
+
+Shared examples test:
+1. Empty state — no `money_transfer` node in output
+2. Valid enum values — correct XML nodes generated
+3. Invalid enum values — `InvalidArgumentError` raised at setter
+4. Nested structures — `sender_address` and `receiver` sub-nodes
+
+## Dependencies
+
+- Auto-loaded by `dependencies.rb` glob pattern (no manual require needed beyond the mixin's own requires)
+- No new gems or external dependencies

data/.kiro/specs/f2025112614-add_money_transfer_payout_attributes_to_payout_rq/requirements.md

@@ -0,0 +1,88 @@
+# Requirements Document
+
+## Introduction
+
+Add Money Transfer Payout attributes support to the Payout transaction request class. The Money Transfer object is an optional nested structure on the Payout request that carries sender, receiver, and transfer metadata required by Visa and Mastercard for money transfer OCT (Original Credit Transaction) payouts.
+
+## Glossary
+
+- **Payout**: A credit card transaction without a reference (OCT) — `GenesisRuby::Api::Requests::Financial::Cards::Payout`
+- **Money Transfer**: An optional nested object within Payout carrying sender/receiver details for regulated money transfers
+- **OCT**: Original Credit Transaction — a credit pushed to a cardholder without a prior debit
+- **Mixin**: A Ruby module included into a request class to add attributes and structure
+- **Restricted Setter**: A setter method that validates the assigned value against a list of allowed options
+
+## Requirements
+
+### Requirement 1: Money Transfer Type Constants
+
+**User Story:** As a developer, I want a constant class defining allowed money transfer types, so that the SDK validates the `type` field.
+
+#### Acceptance Criteria
+
+1. THE SDK SHALL define a `MoneyTransfer::Types` constant class at `Api::Constants::Transactions::Parameters::MoneyTransfer::Types`.
+2. THE class SHALL include values: `visa`, `mastercard`.
+3. THE class SHALL extend `Mixins::Constants::Common` to provide `.all` and `.valid?` methods.
+
+### Requirement 2: Money Transfer Sender Account Number Type Constants
+
+**User Story:** As a developer, I want a constant class defining allowed sender account number types for money transfers.
+
+#### Acceptance Criteria
+
+1. THE SDK SHALL define a `MoneyTransfer::SenderAccountNumberTypes` constant class.
+2. THE class SHALL include values: `iban`, `credit_debit_card`, `savings_checking_investment`, `social_networking_id`, `phone_number`, `bank_account_number_and_bic`, `wallet_id`, `unique_transaction_reference`, `national_id`, `other`.
+3. THE class SHALL extend `Mixins::Constants::Common`.
+
+### Requirement 3: Money Transfer Purpose of Payments Constants
+
+**User Story:** As a developer, I want a constant class defining allowed purpose of payment values specific to money transfers.
+
+#### Acceptance Criteria
+
+1. THE SDK SHALL define a `MoneyTransfer::PurposeOfPayments` constant class.
+2. THE class SHALL include values: `family_support`, `education`, `gift_and_donation`, `medical_treatment`, `maintenance`, `travel`, `small_value`, `liberalized`, `savings_investments`, `other`.
+3. THE class SHALL extend `Mixins::Constants::Common`.
+
+### Requirement 4: Money Transfer Source of Funds Constants
+
+**User Story:** As a developer, I want a constant class defining allowed source of funds values specific to money transfers.
+
+#### Acceptance Criteria
+
+1. THE SDK SHALL define a `MoneyTransfer::SourceOfFunds` constant class.
+2. THE class SHALL include values: `current_account`, `credit_card`, `savings_account`, `deposit_account`, `cash`, `prepaid`, `other_debit_account`, `other_credit_account`.
+3. THE class SHALL extend `Mixins::Constants::Common`.
+
+### Requirement 5: Money Transfer Payout Attributes Mixin
+
+**User Story:** As a developer, I want a mixin module that provides all money transfer payout attributes with validation, so I can include it in the Payout request class.
+
+#### Acceptance Criteria
+
+1. THE mixin SHALL be defined at `Api::Mixins::Requests::Financial::MoneyTransferPayoutAttributes`.
+2. THE mixin SHALL provide `attr_accessor` for plain text fields: `money_transfer_sender_account_number`, `money_transfer_service_provider_name`, sender address fields (`country`, `city`, `line`, `state`, `postal_code`), receiver fields (`first_name`, `last_name`, address fields, `account_number`, `account_number_type`).
+3. THE mixin SHALL provide validated setters (using `allowed_options`) for: `money_transfer_type`, `money_transfer_sender_account_number_type`, `money_transfer_purpose_of_payment`, `money_transfer_source_of_funds`.
+4. THE mixin SHALL provide a date setter/getter for `money_transfer_sender_birth_date` using `parse_date` with `DD_MM_YYYY_L_HYPHENS` format.
+5. THE mixin SHALL provide a protected `money_transfer_payout_attributes_structure` method returning the nested hash structure.
+6. ALL validated setters SHALL allow empty values (`allow_empty: true`).
+
+### Requirement 6: Integration with Payout Request Class
+
+**User Story:** As a developer, I want the Payout request class to include the money transfer mixin, so that money transfer data is serialized in the XML request.
+
+#### Acceptance Criteria
+
+1. THE Payout class SHALL include `Mixins::Requests::Financial::MoneyTransferPayoutAttributes`.
+2. THE `payment_transaction_structure` method SHALL include `money_transfer: money_transfer_payout_attributes_structure` in the returned hash.
+3. WHEN no money transfer attributes are set, THE serialized XML SHALL NOT contain a `money_transfer` node.
+
+### Requirement 7: Test Coverage
+
+**User Story:** As a developer, I want shared RSpec examples for money transfer payout attributes, so that any request class including the mixin can be tested.
+
+#### Acceptance Criteria
+
+1. THE SDK SHALL provide shared examples at `spec/genesis_ruby/shared_examples/api/requests/financial/money_transfer_payout_attributes_examples.rb`.
+2. THE shared examples SHALL test: valid type, invalid type (raises `InvalidArgumentError`), sender fields, sender_birth_date, sender_account_number_type validation, purpose_of_payment validation, source_of_funds validation, sender_address sub-fields, receiver sub-fields.
+3. THE Payout spec SHALL include the shared examples via `include_examples 'money transfer payout attributes examples'`.

data/.kiro/specs/f2025112614-add_money_transfer_payout_attributes_to_payout_rq/tasks.md

@@ -0,0 +1,38 @@
+# Implementation Tasks
+
+## Task 1: Create Money Transfer Constants [done]
+
+- Create `lib/genesis_ruby/api/constants/transactions/parameters/money_transfer/types.rb`
+- Create `lib/genesis_ruby/api/constants/transactions/parameters/money_transfer/sender_account_number_types.rb`
+- Create `lib/genesis_ruby/api/constants/transactions/parameters/money_transfer/purpose_of_payments.rb`
+- Create `lib/genesis_ruby/api/constants/transactions/parameters/money_transfer/source_of_funds.rb`
+
+## Task 2: Create MoneyTransferPayoutAttributes Mixin [done]
+
+- Create `lib/genesis_ruby/api/mixins/requests/financial/money_transfer_payout_attributes.rb`
+- Implement attr_accessors for plain fields
+- Implement validated setters with `allowed_options` for enum fields
+- Implement `money_transfer_sender_birth_date` getter/setter with date parsing
+- Implement protected `money_transfer_payout_attributes_structure` method
+
+## Task 3: Integrate Mixin into Payout Class [done]
+
+- Add `include Mixins::Requests::Financial::MoneyTransferPayoutAttributes` to Payout
+- Add `money_transfer: money_transfer_payout_attributes_structure` to `payment_transaction_structure`
+
+## Task 4: Create Shared Examples [done]
+
+- Create `spec/genesis_ruby/shared_examples/api/requests/financial/money_transfer_payout_attributes_examples.rb`
+- Test empty state (no money_transfer node)
+- Test valid/invalid enum values
+- Test sender_address sub-fields
+- Test receiver sub-fields
+
+## Task 5: Include Shared Examples in Payout Spec [done]
+
+- Add `include_examples 'money transfer payout attributes examples'` to `payout_spec.rb`
+
+## Task 6: Validate [done]
+
+- `bundle exec rake styles` — 0 offenses
+- `bundle exec rake test` — 7107 examples, 0 failures

data/.kiro/steering/product.md

@@ -0,0 +1,15 @@
+# Product Overview
+
+genesis_ruby is an open-source Ruby SDK (gem) for integrating with the Genesis Payment Processing Gateway by emerchantpay.
+
+It provides a client library for:
+- Financial transactions (card payments, 3DS, mobile pay, online banking, vouchers, wallets, crypto, etc.)
+- Non-financial operations (reconciliation, fraud management, tokenization, KYC, billing API, FX, SCA)
+- Web Payment Form (WPF) creation and reconciliation
+- Smart Router API for simplified gateway integration
+- Notification handling for async payment callbacks
+
+The SDK communicates with the Genesis API over HTTPS using XML/JSON request/response payloads. It supports staging and production environments for the emerchantpay and ecomprocessing endpoints.
+
+Current version: defined in `VERSION` file and `lib/genesis_ruby/version.rb`.
+License: MIT

data/.kiro/steering/spec-folder-naming.md

@@ -0,0 +1,16 @@
+---
+inclusion: auto
+description: Enforces spec folder naming convention based on the current Git branch name
+---
+
+# Spec Folder Naming Convention
+
+When creating a new spec, derive the folder name from the current Git branch name:
+
+1. Get the current branch: `git rev-parse --abbrev-ref HEAD`
+2. Strip any prefix up to and including the first `/` (e.g. `feature/`, `bugfix/`, `hotfix/`)
+3. Use the remaining string as the spec folder name under `.kiro/specs/`
+
+Example:
+- Branch: `feature/f2026032402-fixes_on_product_pricing`
+- Spec folder: `.kiro/specs/f2026032402-fixes_on_product_pricing/`