How do I set MyInvois up in the first place? MyInvois setup guide

“How do I set MyInvois up in the first place?” Authorise BigLedger as your intermediary on the MyInvois portal — you need no LHDN credentials and no certificate of your own — then complete your company’s identity, choose the LHDN environment, turn e-invoicing on, and clean up the customer, supplier and item records that decide whether a document is accepted, before you send one document end to end.

By the end of this guide, one real sale will have gone from your sales screen to LHDN and come back Valid — and you will know that the next thousand will do the same. The switching-on part takes an afternoon. The master-data clean-up behind it is what takes a week, and it is where every later problem is either prevented or created, so do not rush it.

Setup, at a glance

Do these in order; Steps 1 to 4 are done for each company. Leave the optional Taxpayer ERP API Credentials block empty unless you mean to use your own MyInvois credentials (the credentials caution, after Step 1).

1. Authorise BigLedger as your intermediary on the MyInvois portal (Step 1).
2. Complete your company’s identity on its record (Step 2).
3. Choose the LHDN environment before you turn anything on (Step 3).
4. Turn e-invoicing on before any document is finalised. A sale finalised earlier never reaches a pool or a report (Step 4).
5. Clean up your customer and supplier records (Step 5) and set the codes on your items (Step 6).
6. Confirm that the background jobs are running for your tenant (Step 7).
7. Send one document end to end and watch it come back Valid (Step 8).

The setup runs across three pages: Step 1 is on this one, Steps 2 to 4 (the company’s own switch-on) are on Switch the company on, and Steps 5 to 8 (the master data, the background jobs and the first document) are on Tidy the data and go live.

Meet GadgetSphere

GadgetSphere Sdn Bhd is bringing three companies online at once: the retail company, the online arm and the distribution company. Each one is a separate taxpayer at LHDN, so each one needs its own authorisation, its own company identity and its own switch-on. The 22 branches sit underneath the retail company and need nothing of their own — but the ~85,000 customer records do, and that is the real work.

What you need to know first

BigLedger submits on your behalf, and you do not need LHDN credentials of your own. BigLedger is configured as your intermediary: you authorise it once on the MyInvois portal, and from then on every submission is signed with a token requested on behalf of your company’s tax number. You do not have to copy a client ID or paste a client secret, and there is no certificate to upload anywhere in BigLedger. If a checklist you have been given says you must, it is out of date.

The one exception, the optional Taxpayer ERP API Credentials block, is after Step 1.

Order matters more than anything else on this page. E-invoicing must be switched on for a company before any document is finalised. This is not a preference — see Steps 3 and 4.

Before you start

• You (or your tax agent) can log in to the MyInvois portal as your company, with rights to appoint an intermediary.
• Your company’s legal details are to hand: tax number, registration number, service-tax number where applicable, industry classification code, and the registered address.
• You know which BigLedger companies are in scope. One authorisation per taxpayer.
• Your BigLedger onboarding contact is reachable this week. A few pieces of the plumbing are switched on for you, and it is much easier to confirm them now than to diagnose them in month one.
• You have decided whether to use your own MyInvois credentials. Most companies should not (why).

Step 1: Authorise BigLedger on the MyInvois portal

Outcome: LHDN knows that BigLedger may submit e-invoices on your company’s behalf.

MyInvois portal (LHDN’s own website), not BigLedger

Log in to the MyInvois portal as your company and appoint BigLedger as your e-invoice intermediary. You will be asked which permissions to grant.

BigLedger’s side is recorded when you switch the company on. When the company is saved with e-invoicing enabled, an LHDN Environment and a tax number (Step 4), BigLedger asks LHDN there and then for a token on behalf of your tax number, once for the test environment and once for the live one, and records an intermediary configuration for each environment LHDN answers. The message Intermediary System Configured Successfully appears either way. If the authorisation was not yet in place, LHDN refuses, nothing is recorded for that environment, and you find out at the first submission (Step 3 names the message). So finish this step before Step 4, and if you switched on too early, ask your BigLedger contact to configure it again for that company and environment.

This authorisation expires. Put the renewal date in a calendar now, with a reminder a month ahead. When it lapses, LHDN refuses BigLedger’s background token refresh, and BigLedger keeps using the last token it was given. Once that token runs out, LHDN refuses every submission for that company at once: the documents stay at IN_QUEUE, the error on each submission queue row is whatever LHDN sent back, and every document looks perfectly fine. Teams lose days to this because the failure looks like a data problem and is not.

If you fill in the Taxpayer ERP API Credentials block

The company’s E-Invoice tab has an optional Taxpayer ERP API Credentials block, with a Production tab and a Sandbox tab. Its on-screen wording describes it as a way to retrieve inbound supplier e-invoices with your own MyInvois credentials, but it does more than that. BigLedger switches to your credentials only when the tab that matches your company’s LHDN Environment has both the Taxpayer Client ID and Client Secret 2 filled in. From then on your credentials request the token for every call to LHDN, including your outgoing submissions.

Client Secret 2 is the one that counts, even though the screen calls it an optional rotation key. BigLedger saves Client Secret 1 but never sends it to LHDN. So if you fill in the Client ID and Client Secret 1 and leave Client Secret 2 blank, the save goes through, submissions keep working, and BigLedger quietly goes on using its own credentials. Nothing on the screen tells you which set is in use, and no error will ever tell you either. Whoever fills the block in should check it on the spot: open the tab that matches LHDN Environment and confirm that the Client ID and Client Secret 2 are both there. If either one is blank, BigLedger is using its own credentials.

Leave the block empty unless you have a reason to use your own MyInvois ERP credentials. If you do fill it in, two things become your job:

• The authorisation above still applies. The token is still requested on behalf of your tax number and kept on the intermediary configuration described above. Your own credentials do not replace that configuration.
• The client secret expires, and nothing switches back for you. BigLedger goes back to its own credentials only when the Client ID or Client Secret 2 is blank, not when your secret has expired. Put the expiry date you entered in a calendar. Before it arrives, renew the secret on the MyInvois portal and update the block, or clear the block.

Next: Step 2: Complete your company’s identity, on the next page.

Step 3: Choose the LHDN environment — before you turn anything on

In brief: set the company’s LHDN Environment to PRODUCTION before you switch e-invoicing on. A blank LHDN Environment means the sandbox: where a test-side configuration exists for the company, documents come back with the same statuses as real ones and have been filed with nobody. The full step, with the one tell that gives a sandbox document away, is Step 3 on Switch the company on.

The sandbox is also the one place you can rehearse a rejection

In brief: a company pointed at the sandbox, with its test-side intermediary configuration in place, gets back the same statuses and files nothing with anybody, so a rejection you cause there reads exactly like a real one. The document you finalise is still a real BigLedger document, so rehearse on a company created for the purpose, never a live one. See the full section.

Step 7: Confirm the background plumbing is switched on

In brief: BigLedger installs a set of default clocks for e-invoicing, all switched on, when your tenant is created, so this is usually a check rather than a task; a clock added to that set after your tenant was created, or one somebody switched off, is the exception. If one is missing, documents stop at one stage and never move on, with no error anywhere. The table of jobs and what each looks like when it works is Step 7 on Tidy the data and go live.

Step 8: Send one document end to end

In brief: finalise one straightforward sale and watch it reach Valid on Internal Submission → To IRB E-Invoice, allowing up to about forty minutes on BigLedger’s default timetable before you worry, and longer if your tenant’s timetable differs or documents are queued ahead of it. Do it only once the company reads PRODUCTION and is enabled: the sale you finalise is a real document. The full step, with what to read if it stops at IN_QUEUE or comes back Invalid, is Step 8 on Tidy the data and go live.

What success looks like

Thirty seconds, on the company you just set up:

1. The company’s LHDN Environment reads PRODUCTION. Check this one first: every check below passes just as convincingly in the sandbox.
2. One real sale, finalised today, shows status Valid on Internal Submission → To IRB E-Invoice.
3. Its record’s Validation URL starts with myinvois.hasil.gov.my, not preprod.myinvois.hasil.gov.my.
4. Its printable version carries an LHDN reference and a QR code.
5. Your supplier details on that e-invoice — your own company block — read correctly: right tax number, right address, right state.

If all five hold, that company is live. Repeat for the next one.

Common mistakes

The mistakes that belong to one part are on that part’s page: enabling the company before choosing the LHDN environment, and finalising documents before enabling e-invoicing, are with Steps 2 to 4; a customer with no address flagged as the e-invoice address is with Steps 5 to 8.

What this setup depends on, and what depends on it

Setup sits upstream of everything else in e-invoicing, so this is the chain to keep in mind when you change it later.

• What must exist first. The MyInvois authorisation (Step 1) must exist before the company is switched on (Step 4), because switching on is what records BigLedger’s side of it. The company record must be complete before the first sale, because every e-invoice copies its supplier block from it. Missing either one, every submission for that company fails, with no fault on any single document.
• What becomes possible. Once a company is live, every finalised sale flows into the e-invoice pools on its own (Pools & Submission Routing), walk-in sales are reported each month in a consolidated e-invoice (The Month-End Cycle), and e-invoices your suppliers issue to you can be fetched from LHDN and paired with your purchases (Incoming Supplier E-Invoices), because the same authorisation serves that call too.
• What breaks elsewhere when a step is skipped or redone. A sale finalised before Step 4 never reaches any pool or report, so the month’s consolidated figures come up short. A company pointed back at the sandbox stops filing anything while every screen still reads Valid. A wrong state on the company address fails every document across every branch at once. Re-pointing the environment also changes which credentials and which intermediary configuration are used, so the next submission can fail with a message you have never seen before.
• What it is used alongside. In practice the setup is done together with the Organisation applet (company, environment, switch), the Customer and Supplier applets (counterparty identity and the e-invoice address), the Tax Configuration applet (the tax type on each line) and the Scheduler applet (the clocks that move documents along). The My E-Invoice Admin applet is where you watch the result.

Related documentation