Merchants

Reference

A merchant is a company that sells fuel, goods or services to fleets through its stores. Its record holds the company's legal and contact identity, one Vietnamese tax code, how the platform integrates with it, and whether it has an account the platform can pay it into.

Overview#

Every store and SKU belongs to one merchant, which serves the tenants of its own country only. Its legal identity is its tax code; it also keeps a separate business-registration number. A merchant is offered to tenants only while it is active and has a receiving account, so a merchant nobody can pay never appears to fleets. Merchants carry no VAT percentage: VAT comes from the platform's fuel VAT schedule for fuel SKUs and from each SKU's own rate otherwise (see VAT rates and VAT-inclusive prices).

Fields#

A new merchant is created when a signed-in user without a company chooses to create a merchant company and enters a Company name and Country. That user becomes the merchant's Merchant Owner and continues to the onboarding steps. See Set up a new organization in the portal.

The portal has no page that edits a merchant's details after that.

Tax code#

• A tax code is either 10 digits (for example 0101234567) or 10 digits, a hyphen and a 3-digit branch suffix (for example 0300555450-001). The branch form is 14 characters long.
• Merchants and tenants use the same rule. Any other value is refused with "Enter a valid Vietnamese tax code: 10 digits, optionally followed by a 3-digit branch suffix (e.g. 0101234567 or 0101234567-001)."
• The field may be blank. A merchant has exactly one tax code; companies with several legal entities or tax codes are not modelled.
• On VAT invoice lines for PVoil refuels, the seller tax code is the merchant's tax code, with surrounding spaces removed. A merchant with no tax code gives a blank seller tax code; the registration number is not used in its place.
• When the platform fetches e-invoices from an invoice provider, it finds the selling merchant by matching the invoice's seller tax code against merchants' tax codes. Tax codes are not required to be unique. When no merchant, or more than one, has the seller's tax code, the invoice may be saved without a merchant rather than guessed; for Petrolimex invoices the platform prefers the merchant already linked to that invoice number, then a Petrolimex-type merchant, then one with an active store. A merchant with a blank tax code cannot be matched this way. See VAT invoices.

Integration types#

New merchants start with None. Stores of PVoil Easy and Petrolimex merchants can be offered for refuelling without a price list, because the integration supplies the price; purchases and work orders still need one. The full rules are on Which stores tenants and drivers can see.

Receiving account#

A merchant is payable when it has a receiving account, checked in this order:

1. An active Goopay account held by the merchant, with an account number set. When there is one, it is the receiving account.
2. Otherwise, a complete bank receiving account: a method, an account number and an account holder name.
3. Otherwise the merchant has no receiving account and is not payable.

• A Goopay account always ranks first. A merchant with both is paid to Goopay, and its bank accounts remain as the fallback. Its Receiving Accounts page then says "Payouts go to your Goopay account (account number). Bank accounts below are a fallback."
• A suspended or retired Goopay account, an inactive wallet, or a tenant's account does not count.
• The platform re-checks whenever the merchant adds, edits or deletes a bank receiving account, and whenever its Goopay account is opened or retired. A merchant whose only bank account is deleted, with no Goopay account, stops being payable; one with a Goopay account stays payable.
• The onboarding step for the receiving account shows complete for a merchant paid through Goopay only.

How bank accounts are entered and how Goopay and bank accounts are used is on Merchant receiving accounts and banks and Set up your receiving account.

What tenants see#

A tenant's users and drivers are offered a merchant, and its stores, only when the merchant is active, in the tenant's country, payable, and not on the tenant's excluded list. Further store-level conditions, such as opening hours and prices, are on Which stores tenants and drivers can see.

Tenant users never open a merchant page: tenant roles hold no permission to view merchants. They meet a merchant by name on its stores and orders, and in the Excluded Merchants card of their tenant page; see Tenants and Stop your fleet from using a merchant. A merchant reaches a tenant's billing identity only through orders between them; see Look up a customer's billing details.

The merchant detail page#

Merchant Owners and Merchant Admins open their own company from Merchants in the sidebar, which goes straight to their merchant's detail page.

Audit logs opens the merchant's change history for roles that can view the audit log; see Audit log.

Finding a merchant#

Platform operators work from the Merchants list, which shows #, Name, Country and Status for every merchant, delisted ones included.

• The search box, "Search by name, email or ID…", matches part of a merchant's name or email, or a merchant's exact ID.
• An ID matches only when the whole number is typed; part of an ID still finds names or emails containing those digits.
• Spaces around the search text are ignored, and text that is not a plain number never causes an error.
• The Status filter offers All, Active and Inactive and starts at All, so a delisted merchant is found with no filter set. Search and the filter combine.
• The Excel export follows the search and filter and has the columns #, Name, Country and Status.

Search never widens what a user may see: a merchant user searching another merchant's ID gets no rows.

Permissions#

Roles and grants come from the permission groups; delisting is limited to platform operators by the status page itself. What delisting does is on Active and inactive records.

Related#

• Tenants
• Which stores tenants and drivers can see
• Stores
• Active and inactive records
• VAT rates and VAT-inclusive prices
• Look up a customer's billing details
• Merchant receiving accounts and banks