Storefront E-Invoice Request

Let a shopper who paid at a branch or on your web store claim their own e-invoice from the storefront, with no account needed. The sale leaves your monthly consolidated e-invoice and goes to LHDN in the shopper’s name, with no approval step and no notice to you: the Portal Request list in My E-Invoice Admin is where you see it, and a failed row there needs somebody.

Overview

A shopper who paid at a branch or on the web store can ask for their own Malaysian LHDN e-invoice from the storefront itself — no account required. They type the cash-bill number with either the PIN printed on the receipt or the amount and date, confirm it is their transaction, fill in their identification number and tax identification number (TIN), and the sale is taken out of the merchant’s monthly consolidated e-invoice and submitted to LHDN as an individual one in their name.

That path is a widget in the Cross Platform Commerce storefront app (the web and mobile Customer Portal), not a screen in an applet. It is placed on a Customer Portal page from CP Commerce Admin, and everything it does runs through a handful of server calls and one queued request run.

This page documents the storefront path only. The merchant’s side of the same pipeline — the pools, the submission and validation queues, the cancellation requests — is the My E-Invoice Admin applet. The equivalent request flow for a tenant-side buyer account, in a different applet and a different repository, is the MY E-Invoice Portal applet.

Where it fits

Screens and menus

There is no menu. The widget renders wherever the layout puts it, usually on a page whose code is E-Invoice — the tracking e-mail BigLedger sends links to https://<website code>/page/E-Invoice.

The widget draws a four-item left rail on desktop and a four-item tab strip on mobile. Three of the four are hidden unless the shopper is signed in. Below 550 px, and between 768 px and 1120 px, the rail labels shorten — Request E-Invoice becomes Request, E-Invoice Cancellation becomes Cancellation, and so on.

Request E-Invoice (the search and the request) is open to everyone. Requested E-Invoices is shown to signed-in shoppers, and to a guest only when the page address carries the key and email of the tracking link BigLedger e-mailed them — a guest who closes that e-mail has no other way back to their requests. E-Invoice Cancellation and E-Invoice History are for signed-in shoppers only, so a guest cannot ask to cancel an e-invoice from the storefront at all.

A Help Centre row sits at the bottom of the rail. It is a label with no click handler and no destination.

Request E-Invoice

Two search modes, as sub-tabs:

• By Date Amount (the default) — Cash Bill/Invoice No., Amount, Transaction Date.
• By Pin — Cash Bill/Invoice No., Pin. Hidden when the widget’s hideByPin parameter is true.

The transaction-date picker does not accept arbitrary dates; see The request window below.

The result is one card (grid view) or one row (list view), showing invoice number, transaction date, currency and amount. Which number is shown as “invoice number” is controlled by the widget’s einvoiceNoDisplayConfig parameter.

Three outcomes:

When the widget’s exportPdfPublicAccess parameter is true and the record’s validation status is Valid, an Export button appears on this screen — for anyone who ran the search, signed in or not.

The request pop-up — Update E-Invoice Profile

Pressing Request opens a modal titled Update E-Invoice Profile. It opens for every guest, and for a signed-in shopper whose customer record is missing any of: TIN, identification number, identification type, e-invoice identification type, e-invoice identification value, e-mail, phone, or a billing/shipping address flagged as the default e-invoice address with address line 1, city, state, country and postal code all filled. A signed-in shopper with all of those already on file skips the modal and the request is sent straight away.

After the request

That last message is shown for every failure of the request call, not only for a duplicate — an authorisation failure or a network error produces the same words.

Requested E-Invoices, Cancellation and History

All three are the same list component with different filters, each with a grid/list toggle, a search box (Search Invoice No/Cash Bill No), an After/Before date range and a status drop-down.

• Requested E-Invoices — counters for All Invoices, In Queue, Validated, Validation Error.
• E-Invoice Cancellation — All Invoices, Requested for Rejection, Cancelled.
• E-Invoice History — All Invoices, In Queue, Validated, Validation Error, Requested for Rejection, Cancelled.

Each counter is a separate query, and what each one reads decides what the shopper should do about it:

So Validation Error always means the document reached LHDN and came back refused — which is the case the shopper cannot re-request, because the request behind it already went through (see Troubleshooting). A request that failed on BigLedger’s own side is folded into In Queue.

The guest version of Requested E-Invoices is a separate, simpler component: no counters, no filters, driven entirely by the key and email in the URL.

The details pop-up

The magnifier icon — always present on a grid card, and on a list row only in the requested, cancellation and history lists — opens a pop-up with invoice number, transaction date, amount and status. When the status is Valid it also renders the LHDN validation QR code, as a base64 PNG held on the record, and an Export button that downloads the rendered e-invoice as E-invoice-<company>-<document type>-<date>-<invoice no>.pdf. On an iOS or Android user-agent the file opens in a new tab instead of downloading, because mobile browsers do not honour the download attribute on blob URLs.

Cancellation

On a validated e-invoice, and only while a countdown of 72 hours from the validation date-time has not run out, a Request for Rejection button appears with the remaining time beside it. It opens a radio list of reasons — Wrong buyer details, Wrong invoice details, Others by default, overridable per widget — with a free-text box when Others is chosen. Once raised, the button is replaced by Requested for Rejection in red.

The countdown is drawn by the widget. Whether the backend independently refuses a late cancellation from this path is not established here.

Configuration

Before you can use it

Placing the widget

CP Commerce Admin → Website → (select website) → Layout Instance → (select layout) → Nodes → (select or add a node) → Main → Widget ID.

The Widget ID drop-down is built by enumerating the shared widget catalogue, so the entry reads EINVOICE WIDGET and its stored value is e-invoice. The storefront resolves that value to the widget.

Widget parameters

The widget reads six parameters from its node’s widgetPlaceHolderConfig.param. Four of them work and two are inert. None of the six has a field in CP Commerce Admin: the widget is registered in the catalogue without a parameter form and the node editor has none for it, so the only way to set them is to edit the layout’s raw JSON on the node’s Json Params tab — which edits the whole layout instance, not the single node. This is recorded as a product finding.

The public key is the whole guest path

The storefront has no anonymous session of its own. On start-up it looks its own hostname up and uses the hostname’s SYS_AKN_WEB_CP_COMMERCE_PUBLIC_KEY to authenticate every call it makes until someone signs in, at which point the user’s own sign-in takes over.

None of the calls in this flow needs the shopper’s own permissions — they need the storefront’s key. So a storefront whose hostname record is missing the public key shows the search form and fails every search with an authorisation error. That is the single most likely cause of “the e-invoice page does not work”.

The request window

The transaction-date picker in the By Date Amount search only accepts dates inside a window derived from the company’s e-invoice request extension period setting:

• No value set — only dates in the current calendar month are selectable.
• A day-of-month value, and today is on or before that day — dates from the start of last month onwards are selectable.
• A day-of-month value, and today is past it — only dates from the start of this month onwards.

This is a restriction on the date picker only. The search itself applies no date window.

Feature visibility / permissions

The widget gates its own features on one thing: whether the session holds an auth token. There are no client-side permission definitions for it, and no permission code is checked on the shopper’s behalf anywhere in this flow.

Fields

Search — By Date Amount

Search — By Pin

The search rejects anything that is neither (invoice number + PIN) nor (invoice number + date + amount) with “Invalid request. Provide either (invoice_no + pin_no) OR (txn_date + txn_amount + invoice_no).”, and returns “No matching eInvoice record found for the given criteria.” when nothing matches.

Update E-Invoice Profile

The form also asks for an optional SST Registration (the only optional identity field), Address Lines 2–5, Postal Code, City, a State chosen from the states of the selected country, and an optional Mobile Number (no -).

• For a signed-in shopper the form opens already filled from their customer record — name, TIN, SST number, identification, e-mail and phone — and from the customer’s address marked as the default e-invoice address, billing addresses first, then shipping. A guest starts from a blank form with Malaysia selected.
• Mobile Number does not reach the e-invoice. It is saved with the address. The buyer details written onto the receipt for a signed-in shopper carry the customer’s phone — the Contact Number — and an address block without the mobile number. Put the number LHDN should see in Contact Number.
• A buyer with no TIN of their own can enter one of the four general TINs LHDN publishes for that case (EI00000000010, EI00000000020, EI00000000030, EI00000000040). The widget accepts it as verified without asking LHDN, and Identification Number stops being required.

Verify TIN. The Update button is disabled until the Verify TIN button has returned a positive result for the exact combination of TIN, identification type and identification number currently in the form. The hint under the TIN field reads Verified in green or Not valid in red. Changing any of the three values after verifying invalidates the result and disables Update again.

What the identity becomes

A guest’s details are not saved anywhere as a customer record. They travel with the queue event and are written onto the document as the buyer JSON.

Lifecycle and effects

This is a request applet feature, not a document applet: nothing here creates a document line, moves stock or posts to the ledger. It changes how an existing sales document is submitted to LHDN, and it records one request.

Step 1 — BigLedger decides whether there is anything to do. Before queuing, it reads the pool entry named by the request and takes one of three courses:

A pool GUID that does not exist raises “Batch Pool Container Not Found”, “Single General Pool Container Not Found” or “Individual Pool Container Not Found”. A signed-in request with no buyer entity GUID is rejected with “Entity hdr guid is null”, and one whose caller is not a login entity of that buyer returns not-authorised.

Step 2 — the queue. The request is queued and picked up straight away. It carries which pool entries are involved, the buyer (the signed-in shopper’s customer record, or the whole guest profile), the course chosen in step 1 and the storefront’s hostname.

Step 3 — what the queued run does. It branches on which pool the receipt sits in.

If the batch-pool branch produces no submission-queue entry, the request is recorded as FAILED rather than SUCCESS — and the receipt is stranded. Its batch pool entry is left processed and failed, with the document’s Submission Type already changed to Individual, so the monthly consolidation passes it by and no individual e-invoice was built: the sale is in neither the consolidated e-invoice nor an individual one until the merchant acts on that pool row (My E-Invoice Admin Applet, PROCESSED / FAILED).

SUCCESS means the e-invoice was built and queued for submission, not that LHDN has received it — the merchant’s ordinary submission run sends it, and its status is read on the e-invoice itself.

Step 4 — the request record. Either way one request record is created, carrying the request status, the sales document and its type, transaction date and amount, the invoice number, the PIN, the To IRB e-invoice, the five server and five client document numbers, and any validation message. For a guest it additionally carries the e-mail address and a 12-character access key — the first 12 characters of a random UUID.

Step 5 — the guest e-mail. When the row has both an access key and an e-mail, BigLedger sends one e-mail, subject “Trace your e-invoice request status”. On SUCCESS the body says the request has been processed and offers a Track Your Request link; on FAILED it says the request failed and to contact the relevant authority. The link first checks that the key and e-mail match a request record and then redirects the shopper to https://<website code>/page/E-Invoice?key=…&email=…. The widget reads those two query parameters and shows the guest’s requested-invoice list.

What the merchant sees. Every request is logged in the My E-Invoice Admin Applet under Internal Submission → Portal Request — one record per request, SUCCESS or FAILED, whether it came from this widget or from the customer portal, which runs the same processor. The request also surfaces as a changed pool row and a new submission-queue entry, with the buyer’s name, identification, TIN and address now on the document. There is no approval step and no notification to the merchant that a shopper asked: Portal Request is the list to read, and a FAILED row on it is the one that needs somebody.

Related applets

• CP Commerce Admin — where the widget is placed on a page, and where every other storefront setting lives.
• My E-Invoice Admin — the merchant’s side of the pipeline this feeds: the pools, the submission and validation queues, the cancellation requests.
• MY E-Invoice Portal — the same request made from a tenant-side buyer account rather than a storefront. Different applet, same underlying records.
• Customer — where a signed-in shopper’s identification, TIN and default e-invoice address are stored and can be corrected.
• POS General — the cash bill most storefront e-invoice requests are about, and where its PIN comes from.

Troubleshooting

Related documentation

• CP Commerce Admin applet — the console this widget is placed from.
• Push Notification Configuration — the other CP Commerce feature documented screen by screen.
• E-Invoice module — how the Malaysian e-invoice pipeline fits together.
• E-Commerce module — the storefront this widget lives in.