[ACL-292] Add sub-merchant support for payments and payouts

[federico1525]

Summary

This PR adds comprehensive sub-merchant functionality to the TrueLayer PHP client to support regulatory compliance and business transparency requirements.

Features Added

• ✅ Sub-merchant support for both payments and payouts
• ✅ Business client ultimate counterparty with address or registration number
• ✅ Business division ultimate counterparty for internal divisions
• ✅ Fluent API with proper method chaining and validation
• ✅ Client factory methods: ultimateCounterparty(), paymentSubMerchants(), payoutSubMerchants()
• ✅ Input validation (MCC format, field lengths, required fields)
• ✅ Comprehensive test coverage (10 integration tests, 57 assertions)
• ✅ Updated documentation with usage examples

Version

• 3.3.0 - Minor version bump (backward compatible)
• Updated CHANGELOG.md with release date
• Updated README.md with comprehensive documentation

API Examples

Payment with Business Client Sub-Merchant

$subMerchants = $client->paymentSubMerchants()
    ->ultimateCounterparty(
        $client->ultimateCounterparty()
            ->businessClient()
            ->address($address)
            ->commercialName('My Business Ltd')
            ->mcc('5411')
    );

$payment = $client->payment()
    ->amountInMinor(1000)
    ->currency('GBP')
    ->paymentMethod($paymentMethod)
    ->user($user)
    ->subMerchants($subMerchants)
    ->create();

Payout with Business Client Sub-Merchant

$subMerchants = $client->payoutSubMerchants()
    ->ultimateCounterparty(
        $client->ultimateCounterparty()
            ->businessClient()
            ->registrationNumber('12345678')
            ->commercialName('Payout Business Ltd')
            ->mcc('6011')
    );

$payout = $client->payout()
    ->amountInMinor(500)
    ->beneficiary($beneficiary)
    ->currency('GBP')
    ->merchantAccountId($accountId)
    ->subMerchants($subMerchants)
    ->create();

Test Plan

• All existing tests pass (220 tests, 1,105 assertions)
• New integration tests added (10 tests, 57 assertions)
• Validation tests for MCC format, field lengths, and required fields
• Fluent API method chaining tests
• Request payload validation tests
• Both payment and payout sub-merchant scenarios tested

Breaking Changes

None - This is a fully backward compatible addition. All existing APIs remain unchanged.

Related

• JIRA Ticket: ACL-292
• Addresses regulatory compliance requirements for sub-merchant identification

🤖 Generated with Claude Code