Merchant Applet

Purpose and Overview

The Merchant Applet is the administrative hub for onboarding and managing every merchant on the platform. It handles the full lifecycle — from creating a merchant identity and configuring payment gateway credentials, through to managing contracts and auditing every change made to a merchant record.

A short introduction to the Merchant Applet:

A a webinar for the Merchant Applet:

Key Features Overview

Who Benefits from This Applet?

Platform Administrators:

• Centralized creation and management of merchant profiles
• Secure storage of API keys and payment gateway credentials
• Real-time status monitoring (Active vs. Deactivated)
• Configuration of merchant types, entity types, and AR/AP categories

Merchant Relationship Managers:

• Structured onboarding workflow for new partners
• Full visibility into active, expiring, and historical contracts
• Ability to update merchant profiles, contact details, and addresses
• Audit trail of every administrative change made to a merchant record

Finance & Compliance Teams:

• Centralized repository of all merchant contracts and rate cards
• Credit limit and credit term management per merchant
• Complete audit logs for every modification in the system
• Verification of merchant status and eligibility before transactions

What Problems Does This Solve?

The Partner Management Friction Problem:

Managing a large ecosystem of merchants through spreadsheets or fragmented systems creates significant operational risk:

• Scattered merchant profile data across multiple departments
• Manual handling of sensitive Merchant Keys, creating security exposure
• Lost or undocumented contractual agreements and rate cards
• No formal approval process or audit trail for merchant state changes
• Difficulty verifying compliance for every registered merchant

The Merchant Applet Solution:

• Structured Onboarding Workflow — standardized field-driven creation of merchant identities, credentials, and configurations
• Secure Credential Repository — dedicated storage of Payment Gateway (PGW) codes, merchant keys, and return URLs
• Contract Lifecycle Hub — integrated tracking of formal agreements with rate cards and validity controls
• Comprehensive Event Logging — audit trails for every profile and contract modification
• Flexible Segmentation — define merchants by type (Corporate vs. Individual), entity type, and AR/AP category

Key Features

Key Concepts

Understanding the Merchant Framework

Every merchant in the system is built from three layers:

Merchant Lifecycle

New Partner Request
│
├── Merchant Creation ──→ Register ID, Name, Company, Entity Type, Keys
│   │
│   └── Credential Setup ──→ PGW Merchant Code, Merchant Key, Return URLs
│       │
│       └── Contract Creation ──→ Rate Card, Payment Channels, Validity Period
│           │
│           └── Active & Ongoing ──→ Audit Trail logs every change

Entity Type vs. Merchant Type

These two fields are often confused because they both classify the merchant — but they operate at completely different levels.

Entity Type is functional — it drives how the system behaves. It controls which applets recognize the record, how financial entries are categorized (AR vs AP), and what workflows the entity participates in. Changing it has downstream consequences across the platform.

Merchant Type (CORPORATE vs INDIVIDUAL) is descriptive — it classifies the business structure for reporting and documentation. It tells you what kind of business the merchant is, but does not change how the system routes transactions or which applets see the record.

The two are not fully independent. Merchant Type only becomes meaningful on records where Entity Type includes MERCHANT — it would not make sense on a pure SUPPLIER or EMPLOYEE record. Think of it as a sub-classification that sits beneath Entity Type: Entity Type establishes the functional role, Merchant Type describes the business form within that role.

Navigation Menu

The applet sidebar contains four main sections, plus Settings and Personalization:

Merchant Admin

The primary working area. Lists all registered merchant profiles and is the entry point for creating new merchants. This is where the full create/edit lifecycle happens — from initial registration through credential setup to status management.

Contract Container

Lists all merchant contracts. A contract formalizes the commercial relationship between your platform and a merchant — it defines the rate card (what fees apply per payment channel) and the validity period of the agreement.

Report

Provides reporting views on merchant data — distributions, status breakdowns, and performance trends across the merchant portfolio.

Audit Trail

A read-only log of every change made across all merchant records and contracts. Used by compliance teams to trace who changed what and when. Every create, edit, and status change is recorded here with a timestamp and the user responsible.

Merchant Admin

Listing

Create

Required fields: Merchant ID, Merchant Name, Merchant Company, Company Registration No / ID Number, Entity Type, AR/AP Type, PGW Merchant Code, Merchant Key, Status

Optional fields: Merchant Type, Description

Fields that need context:

Edit

The edit form contains all the same fields as create, plus additional configuration tabs that manage the deeper aspects of the merchant relationship.

Action buttons on the edit form:

Details Tab

Peppol Config Tab

Peppol IDs sub-tab

Manages the Peppol participant identifiers for this merchant. A Peppol ID is the network address that uniquely identifies a business on the Peppol network — similar to an email address, but for invoices.

Notification Config sub-tab

Channels: Peppol, Email, Other UCC Channels (Telegram, Facebook, etc.), Through Customer Portals

The Peppol channel is only available if the merchant has a valid Peppol ID configured in the Peppol IDs sub-tab.

Login Tab

Fields: User Email, Rank, Status

Action buttons:

Contract Tab

Lists all contracts associated with this merchant. Contracts are created and managed in the Contract Container section of the applet, but this tab gives you a quick view of all agreements for this specific merchant without leaving the merchant profile.

Expanding a contract row reveals its Rate Card — the pricing schedule that defines what fee applies per payment channel (e.g., 1.5% MDR for Credit Card, flat RM 0.50 for FPX). This is a read-only summary view; to create or edit rate cards, open the contract in the Contract Container. For a full breakdown of how the Rate Card works, see the Rate Card Tab section below.

Return URL Tab

Fields: Return URL Code, Return URL Name, Success Return URL, Error Return URL

Success and Error Return URLs each have a toggle — the URL field only appears when the toggle is enabled.

Tax & Billing Tab

Payment Config Tab

Supported settlement types include: Bank Transfer, Cash, Cheque, Credit Card, E-Wallet, FPX/eMandate, Payment Gateway, Membership Points, Open Credit, Voucher, and Others.

Address Tab

Each address has a Set as Default toggle. When a merchant has more than one address of the same type, marking one as default tells the system which address to use by default for document generation, invoicing, and correspondence. The address listing shows (default) next to the address type label for the designated address. Only one address per type can be set as default at a time — setting a new default automatically clears the previous one.

Contact Tab

Company Linking Tab

Merchant Branch Tab

Each branch record is divided into four sections:

Identity & Mapping

Branch Address

Standard contact and location fields: Address Name, Email, Phone Number, Address Lines 1–5, Country, State, City, Postal Code.

Control Account

These fields tie this branch’s transactions to specific GL accounts — determining where the platform posts financial entries for this branch.

Output Tax / Input Tax

Configures the tax codes applied when this branch transacts. Output tax is applied on sales; input tax is applied on purchases. Tax type and rate fields are read-only — they auto-fill when you select a tax code.

E-Invoice

Credit Limit and Terms Tab

Manages the credit facilities extended to this merchant. Contains two nested sub-tabs:

Credit Term sub-tab

Credit Limit sub-tab

You can either:

• Existing Credit Limit — select a pre-configured credit limit profile from the system
• New Credit Limit — create a new limit with a code, name, status, currency, and limit amount

Fields: Credit Limit Code, Credit Limit Name, Status, Currency, Credit Limit Amount

Logo Tab

Contract Container

How Merchant and Contract relate

A merchant record and a contract are created separately, and in that order:

1. Create Merchant     →  registers identity and payment credentials
2. Sign agreement      →  commercial terms agreed outside the system
3. Create Contract     →  formalizes terms in the system (rate card, payment channels)
4. Merchant goes live  →  system can now route payments and apply fees

A merchant can exist without a contract — registered but not yet live. The contract is what activates them. Every time the merchant processes a payment, the system looks up their active contract to answer two questions:

• Is this payment method allowed? (is it in the rate card?)
• What fee do we take? (what is the MDR or flat rate for this channel?)

The relationship is not 1 merchant = 1 contract. A contract is tied to a specific merchant + platform company pair. This means:

• One company can have contracts with many merchants
• One merchant can have contracts with multiple companies on your platform (each with their own rate card)
• A merchant can also have multiple contracts over time as agreements renew or terms change — old contracts remain on record for audit purposes

Contracts are kept separate from the merchant profile because commercial terms change independently — a contract can be renewed or renegotiated without touching the merchant’s identity or credentials.

Listing

Create

Required fields: Contract Name, Merchant, Contract Company, Status

Auto-generated: Contract Code (system-generated, read-only)

Fields that need context:

Edit

The edit form contains all the same fields as create, plus tabs for managing the commercial details of the contract.

Details Tab

Rate Card Tab

The rate card is the pricing schedule inside this contract — it defines what fee the merchant pays per payment method.

Each entry pairs a Payment Channel (e.g., Credit Card Visa, FPX, E-Wallet) with a Charge Rate — either a percentage of the transaction amount or a flat fee per transaction. The percentage form is called MDR (Merchant Discount Rate): if the rate is 1.8% and the merchant processes RM 100, the platform keeps RM 1.80 and the merchant receives RM 98.20.

A single contract can have multiple payment channels, each with its own rate. This is normal — credit card transactions typically carry a higher MDR than FPX or e-wallet transactions because the underlying processing costs differ.

Without a rate card, the system has no fee to apply when the merchant transacts — so this must be configured before the merchant goes live.

Annex Tab

Document storage for this contract record. Upload the signed physical contract PDF, amendment letters, approval emails, or any other supporting paperwork that belongs alongside this agreement. This is not a functional tab — it does not affect system behavior. It exists so the digital contract record and the physical paperwork stay together in one place.

Report

What it shows per row: Merchant, Payment Channel, Currency, No. of Transactions, Total Transaction Amount, VAT %, PC Charges, UNIPIN Charges

Columns that need context:

Where the data comes from: The system aggregates transaction data automatically from payment activity — you do not feed it anything manually. It reads from the same merchant and payment channel records configured in Merchant Admin and Contract Container.

What you can do with it:

• View the monthly summary per merchant and channel
• Click a row to drill into the detail of that specific entry
• Export to CSV or Excel for further analysis

It does not post to any other applet and has no financial impact — it is purely a reporting and export tool.

Audit Trail

• The exact field that changed and the before/after values
• The user who made the change
• The timestamp of the change
• The merchant or contract record affected

Use this section to investigate unauthorized changes, trace who approved a merchant activation, or verify the history of a specific credential update. The audit trail cannot be edited or deleted.

Settings

Field Settings

Controls which fields are shown or hidden across the merchant create and edit forms. For example, the Entity Type field can be hidden if your platform only operates with a single entity type.

Default Selection

Sets system-wide default values pre-populated when creating a new document:

Permission Management

Controls who can perform which actions within the applet. Four layers of permission management are available:

Webhook Configuration

Configures outgoing webhooks that fire when specific events happen in the merchant applet — for example, notifying an external system when a new merchant is created or a contract status changes. Used for integration with external platforms or notification systems.

Feature Visibility

Controls which features within the applet are visible to end users. Use this to simplify the interface for specific user groups by hiding features they do not need.

Personalization

User-level customization of the applet experience. Unlike Settings (which are system-wide), Personalization settings apply only to the individual user configuring them.

Personal Default Settings

Sets personal default values for fields on new documents — overrides the system-wide defaults from Settings for this user only.

Sidebar Configuration

Controls which items appear in the sidebar navigation and in what order. Users can hide menu items they do not use to reduce visual clutter and keep their working area focused.

Related Applets

How This Applet Connects to Others

The Merchant Applet has no direct navigation links to other applets — there are no buttons that take you from here into another applet. Instead, the data you configure here is shared with downstream applets automatically. When you register a merchant, set a Peppol ID, or configure a credit limit, those values are immediately available wherever the platform needs them — you do not need to enter them again elsewhere.

Customer Applet & Employee Applet

Merchants, customers, and employees are all stored as entity records under the same unified identity framework. The only difference between a merchant record and a customer record is their classification — the underlying structure is identical.

This has a practical implication: if a partner is both a merchant on your payment platform and a customer who buys from you, they do not need two separate records. A single entity can carry both classifications at once, and both applets will recognize them correctly.

Credit limits and credit terms configured here use the same credit management system as the Customer Applet — so a credit profile set up in either applet is visible in both.

My E-Invoice Admin Applet & My Peppol Admin Applet

The Peppol Config tab in this applet is the source of truth for a merchant’s Peppol network identity. When you register a Peppol ID here, the E-Invoice and Peppol Admin applets read it automatically — they do not have their own place to enter it.

This means the e-invoice workflow depends on this applet being set up correctly first:

Merchant Applet
└── Peppol Config Tab (register Peppol ID here)
        │
        ├── My E-Invoice Admin Applet — uses it for LHDN submission
        └── My Peppol Admin Applet   — uses it for Peppol network routing

If a merchant’s Peppol ID is missing or incorrect here, e-invoice submissions for that merchant will fail downstream. Always configure Peppol IDs in this applet before attempting any e-invoice workflow for a merchant.

General Ledger Applet

GL account codes can be attached to a merchant’s intercompany branch to define which ledger accounts the merchant’s transactions post to. Those GL codes are maintained in the General Ledger Applet — this applet only reads and selects from them.

Seller Admin Applet

The Seller Admin Applet manages the operational side of a merchant’s activity — order creation, fulfillment queues, and pick-pack workflows. It uses the merchant identity created here as its foundation.

The division of responsibility is:

• Merchant Applet — register the merchant, set up credentials and contracts (who they are)
• Seller Admin Applet — process their orders and fulfillment (what they are selling and shipping)

Summary

FAQ

Q: Can a merchant have multiple contracts? A: Yes. The Contract Container tracks all contracts for all merchants. A merchant can have successive contracts as agreements renew, giving a full historical record of the commercial relationship over time.

Q: What is the difference between PGW Merchant Code and Merchant Key? A: The PGW Merchant Code is the identifier the payment gateway uses to know which merchant account to route a transaction to — think of it as the merchant’s “account number” with the gateway. The Merchant Key is the secret credential used for API authentication — think of it as the merchant’s “password.” Both are required for secure payment routing.

Q: What happens if I change a Merchant Key? A: The change is logged in the Audit Trail. You must also update the Merchant Key in any connected integration or payment gateway configuration to avoid transaction failures caused by credential mismatch.

Q: Can I deactivate a merchant without deleting them? A: Yes. Setting the Status to DEACTIVATE disables the merchant’s access and transactions on the platform while preserving all their data, contracts, and audit history. This is the preferred approach over deletion, which is permanent.

Q: What does Entity Type affect downstream? A: Entity Type determines how financial entries are categorized when transactions are posted. A merchant tagged as CUSTOMER generates Accounts Receivable entries. One tagged as SUPPLIER generates Accounts Payable entries. Getting this right at the time of onboarding prevents GL mis-postings later.

Q: Is there support for multi-currency merchants? A: Yes. Credit limits can be denominated in specific currencies, and merchant-level currency settings drive how financial settlements are calculated and posted. The AR/AP Type field also factors into multi-currency settlement logic.

Q: What is the Merchant Contract Key? A: The Merchant Contract Key is a system-generated unique identifier for the contract record itself — distinct from the Merchant ID and the Merchant Key. It is used internally for API calls and cross-system references to uniquely identify a specific contract without ambiguity.

Q: Why would a contract have multiple payment channels with different rates? A: Different payment methods carry different processing costs. Credit card transactions typically carry higher MDR (Merchant Discount Rate) than FPX or e-wallet transactions. The rate card lets you formalize these different rates per channel in a single contract, so the correct fee is applied automatically for each transaction type.