README

A lightweight Merchant and Vendor Alias management package designed to support the x-change financial workflow platform.

🧭 Overview

3neti/merchant provides a minimal, focused domain layer for:

• Merchant management
• Vendor alias assignment and validation
• Reserved alias protection
• Clean integration with Laravel applications

It is intentionally small, strict, and domain-focused, making it ideal as a supporting package in larger financial systems like x-change.

🎯 Core Concepts

Merchant

Represents a business entity that can:

• Own vendor aliases
• Act as a payable / routing identity
• Be linked to a user

Vendor Alias

A short, human-readable identifier used for:

• Payment routing
• Merchant identification
• External references

Example:

GCASH
SHOP123
VNDR01

⚙️ Features

✅ Merchant Model

• Eloquent model with factory support
• Basic fillable attributes
• User ↔ Merchant relationship support

✅ Vendor Alias Service

Handles:

Normalization

$alias = $service->normalize(' shop1 ');
// SHOP1

Validation Rules

• ASCII only
• Must start with a letter (A–Z)
• Length: 3–8 characters
• Uppercase letters and digits only

$service->validate('SHOP1'); // true
$service->validate('shop');  // false

Availability Checks

• Prevents duplicate aliases
• Prevents use of reserved aliases

$service->isAvailable('SHOP1');

✅ Validation Rule: ValidVendorAlias

Laravel validation rule enforcing:

• Strict format validation (no auto-correction)
• Reserved alias protection
• Configurable length limits

use LBHurtado\Merchant\Rules\ValidVendorAlias;

$request->validate([
    'alias' => ['required', new ValidVendorAlias],
]);

🔒 Design Philosophy

1. Strict Input Validation

Aliases are not auto-corrected.

• shop ❌ invalid
• SHOP ✅ valid

This ensures:

• Predictability
• Consistency
• Financial safety

2. Separation of Concerns

Responsibility	Layer
Normalization	Service
Validation	Rule
Persistence	Database
Business logic	Application

3. Financial-System Ready

Designed for:

• Payment routing
• Payable identities
• Voucher / Pay Code systems

🧪 Test Coverage

All tests passing:

Tests: 25 passed (58 assertions)

Covered Areas

• Merchant model
• User ↔ Merchant relationship
• Alias normalization
• Alias validation (valid + invalid cases)
• ASCII enforcement
• Length constraints
• Reserved alias handling
• Error messaging

🧱 Database Tables

vendor_aliases

Stores assigned aliases.

reserved_vendor_aliases

Stores protected aliases (e.g. system, EMI, brands).

Example:

alias	reason
ADMIN	System
ROOT	System
GCASH	EMI

⚙️ Configuration

// config/merchant.php

'alias' => [
    'min_length' => 3,
    'max_length' => 8,
    'pattern' => '^[A-Z][A-Z0-9]{2,7}$',
],

🚀 Usage

Assign Alias

$service = new VendorAliasService;

if ($service->isAvailable('SHOP1')) {
    // assign alias
}

Validate Input

$request->validate([
    'alias' => ['required', new ValidVendorAlias],
]);

🧭 Role in x-change

In the x-change architecture, this package provides:

• Merchant identity layer
• Vendor alias routing key
• Integration point for payable flows

Flow:

User → Merchant → Vendor Alias → Voucher / Pay Code → Disbursement

📌 Key Takeaways

• This package is intentionally simple and strict
• It enforces clean, uppercase, deterministic identifiers
• It is built for financial-grade systems, not loose UX inputs

🔥 Future Enhancements (Optional)

• Alias assignment actions
• Merchant profile DTOs
• Alias → Merchant resolver service
• Integration with voucher payable specifications

📄 License

Proprietary / Internal Use