3neti/merchant

3neti/merchant

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

Supported Platforms

• PHP 8.3 or 8.4
• Laravel 12 or 13
• Pest 3 or 4 for package development

Install the current minor release with:

composer require 3neti/merchant:^1.2

🧭 Overview

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

• Merchant management
• Reusable QR merchant presentation profiles
• 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

QR Merchant Profile

The merchant record may also hold reusable QR presentation fields:

• display name;
• city;
• four-digit merchant category code;
• an approved display-name template.

MerchantProfileRepositoryContract resolves and updates the profile for a user. MerchantDisplayNameRenderer renders the provider-facing label with the configured length and uppercase policy.

These fields are presentation metadata. They do not identify a funding Account, derive a VCA, classify provider evidence, or authorize settlement.

⚙️ 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

3. Financial-System Ready

Designed for:

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

🧪 Test Coverage

All tests passing:

Tests: 28 passed (71 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:

⚙️ Configuration

// config/merchant.php

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

'qr_profile' => [
    'default_city' => env('MERCHANT_QR_DEFAULT_CITY', 'Manila'),
    'default_category_code' => env('MERCHANT_QR_DEFAULT_CATEGORY_CODE', '0000'),
    'default_name_template' => env('MERCHANT_QR_DEFAULT_NAME_TEMPLATE', '{name} - {city}'),
    'fallback_name' => env('MERCHANT_QR_FALLBACK_NAME', 'Account Holder'),
    'uppercase' => env('MERCHANT_QR_UPPERCASE', false),
],

Keep templates limited to application-approved choices. A consumer such as x-change must validate provider length constraints before persisting a profile.

🚀 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
• Provider-neutral QR presentation metadata
• 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