Data Model - Merchant

Merchant Overview

The Merchant data model defines the structure for merchant identification and hierarchy information in payment transactions. This model encapsulates merchant credentials, hierarchy relationships, and business entity information.

Data Model Structure

Parameter	Type	Description
merchantId	String	Primary merchant identifier assigned by the platform Format: Alphanumeric string Usage: Unique identifier for merchant authentication and transaction routing Examples: "20001", "20011"
merchantName	String	Primary merchant business name Format: UTF-8 encoded string Usage: Display name for merchant identification and reporting Examples: "Betty", "ABC Corporation"
subMerchantId	String	Sub-merchant identifier for hierarchical structures Format: Alphanumeric string Usage: Identifies sub-merchant within primary merchant hierarchy Examples: "2000101", "2000102"
subMerchantName	String	Sub-merchant business name Format: UTF-8 encoded string Usage: Display name for sub-merchant identification and reporting Examples: "Devin", "XYZ Subsidiary"

Merchant Hierarchy Structure

Primary Merchant

• Role: Main business entity registered with the platform
• Responsibilities: Primary account holder, settlement recipient, compliance management
• Identification: Unique merchantId assigned by platform

Sub-Merchant

• Role: Subsidiary or branch under primary merchant
• Responsibilities: Transaction processing, local operations, customer service
• Identification: Sub-merchantId linked to primary merchantId

Implementation Examples

{
  "merchantId": "20001",
  "merchantName": "Betty"
}

{
  "merchantId": "20001",
  "merchantName": "Betty",
  "subMerchantId": "2000101",
  "subMerchantName": "Devin"
}

{
  "merchantId": "20001",
  "merchantName": "ABC Corporation",
  "subMerchantId": "2000102",
  "subMerchantName": "XYZ Subsidiary"
}

Business Use Cases

Single Merchant Operations

• Small Businesses: Direct merchant registration and operation
• Simple Structure: Single point of contact and settlement
• Implementation: Use only merchantId and merchantName

Multi-Tier Merchant Operations

• Franchise Operations: Multiple locations under single parent company
• Agency Networks: Independent agents operating under main merchant
• Implementation: Use sub-merchant structure for hierarchical management

Platform Integration

• API Authentication: merchantId used for request authentication
• Transaction Routing: Sub-merchantId for specific business unit routing
• Settlement Management: Hierarchical settlement structure support

Security and Compliance

Merchant Authentication

• ID Validation: All merchant IDs must be pre-registered and validated
• Access Control: Sub-merchants inherit permissions from primary merchant
• Audit Trail: Complete tracking of merchant hierarchy changes

Data Management

• Hierarchy Integrity: Maintain proper parent-child relationships
• Name Consistency: Ensure merchant names match official registration
• Update Procedures: Proper procedures for merchant information updates

Regulatory Compliance

• Business Registration: All merchants must have valid business registration
• KYC Requirements: Know-your-customer compliance for all merchant levels
• Reporting Requirements: Hierarchical reporting for regulatory compliance