How to retrieve and verify company TIN number?
To facilitate the retrieval of Tax Identification Number (TIN), there are three (3) channels available for taxpayers:
• Check the TIN via the MyTax Portal (e-Daftar menu);
• Contact the HASiL Contact Centre (03-8911 1000); or
• Visit the nearest LHDNM offices.
How to obtain Client ID and Client Secret for Sandbox?
Taxpayers can apply the Client ID & Client Secret for API Sandbox Environment via the MyInvois Customer Feedback Form feedback.myinvois.hasil.gov.my. Kindly provide the information as follows to request for Client ID and Client Secret:
- Tax Identification Number (TIN) - excluding Employer’s (E) No.
- New Business Registration Number
- Company Name
- Company Email Address
- Name of ERP System
What are the environment URLs?
| Env | Registration Portal | Invoicing Portal | System API | Identity Service |
|---|---|---|---|---|
| PROD | TBD | myinvois.hasil.gov.my | api.myinvois.hasil.gov.my | api.myinvois.hasil.gov.my |
| SANDBOX | TBD | preprod.myinvois.hasil.gov.my | preprod-api.myinvois.hasil.gov.my | preprod-api.myinvois.hasil.gov.my |
How to submit an e-Invoice in the MyInvois portal?
There are two (2) options for taxpayers to submit their invoices via MyInvois Portal for LHDNM validation:
Individual Creation: Taxpayers can create e-Invoices individually by completing a form with all the required fields; or
Batch Upload: Taxpayers can upload a certain number of e-Invoices in batches by uploading pre-defined Microsoft Excel spreadsheet to the portal, containing the necessary invoice information. The spreadsheet format will be available when MyInvois Portal is launched. Kindly visit to e-Invois microsite for latest information.
What are the various document statuses within the e-Invoice workflow?
The invoice is stored in the local database with a specific status. The status is an integer value, which could be one of the following:
| Status | Value | Note |
|---|---|---|
| Submitted | 1 | This means the invoice has passed initial structure validations but is still pending additional validations to be completed |
| Valid | 2 | The status of a successful invoice validation |
| Invalid | 3 | The status of a submitted invoice with validation issues |
| Cancelled | 4 | The status of an invoice cancelled by the issuer |
What are UBL JSON Value Mappings?
In the UBL JSON, every attribute value should be paired with a key “_” to be compliant with UBL.
For Example: value for InvoiceTypeCode should be represented as “_” : “02” which refers to the Credit Note Invoice Type code.
Which login API should be used by the Taxpayer or Intermediary?
Taxpayers should use the Login as Taxpayer System when submitting their own documents. However, taxpayers who act as service providers, submitting documents on behalf of their customers, should use the Login as Intermediary System.
Which Client ID and Client Secret should Intermediaries utilise to submit on behalf of Taxpayers?
Intermediaries should use their own Client ID and Client Secret to submit on behalf of Taxpayers.
What are the available APIs in the Sandbox and Production Environment?
The table below provides details about the APIs available in the Sandbox and Production environment. “Actual APIs” are functional and will return actual API responses, whereas “Stub APIs” are temporary endpoints that return mock API responses. Stubs serve as stand-ins until the actual API implementation is made available. A stub API mimics the real API’s structure and behavior in a controlled manner, providing predictable responses. At this point in time, the actual API for these stubs are under development.
| # | API | Actual / Stub |
|---|---|---|
| 1 | Login as Taxpayer System | Actual |
| 2 | Login as Intermediary System | Actual |
| 3 | Get All Document Types | Actual |
| 4 | Get Document Type | Actual |
| 5 | Get Document Type Version | Stub |
| 6 | Get Notifications | Stub |
| 7 | Validate Taxpayer’s TIN | Actual |
| 8 | Submit Documents | Actual |
| 9 | Cancel Document | Actual |
| 10 | Reject Document | Actual |
| 11 | Get Recent Documents | Actual |
| 12 | Get Submission | Actual |
| 13 | Get Document | Actual |
| 14 | Get Document Details | Actual |
| 15 | Search Documents | Stub |
How to get sample payload?
You can download the JSON collection file from the Sample page for the sample JSON request. Then, follow the steps on how to test the APIs to get the response for each APIs.
How to test APIs via Postman?
The guidance on how to test the API’s can be found on the Postman Page.
How to get sample response from each API?
You can download the JSON collection file from the Postman page for the sample JSON request. Then, follow the steps on how to test the APIs to get the response for each APIs.
What are the code and value required for tax exemption?
The Software Development Kit (SDK) page and Postman have been updated on 24 May 2024. Tax Exemption code ‘E’ is now added into SDK for Tax Type code. The real value should correspond to the tax type code available at sdk.myinvois.hasil.gov.my/codes/tax-types.
What to do if an Error 400 code appears in API when validating taxpayers’ TIN number?
This API returns HTTP status code 400(BadArgument) if the TIN or any of the input parameters does not match the argument structure. Taxpayers need to check their TIN number format is correct.
Can an e-Invoice be issued with a negative value?
Yes. Negative values are allowed for fields within Document Submission.
Is there a limit to the number of buyer email addresses that can be added to the e-Invoice?
No, The MyInvois System supports a single email as long as the field does not exceed the field size limit of 320 characters.
How can the file size of an XML document be reduced if it exceeds the 300KB submission limit?
For cases where an invoice exceeds the 300KB size limit, you may use minification. Minification refers to the process of reducing the size of a file or code without changing its functionality. By removing unnecessary whitespace, comments, and formatting, minification significantly reduces the overall file size while preserving the original functionality of the invoice.
How to validate TIN starting with the number ‘0’?
To validate the Tax Identification Number (TIN) for taxpayers, it is essential to remove any initial zeros that come after the TIN prefix for successful validation. For example, where the TIN of a taxpayer is ‘C01234567890’, the zero after the prefix ‘C’ needs to be excluded, resulting in ‘C1234567890’.
Where can taxpayers obtain guidance on Digital Signature?
The comprehensive guidance on Digital Signature creation and validation can be found on the Signature page.
How to acquire Digital Signature?
The issuer of the documents will have to use a valid digital certificate that is issued by a certificate authority (CA) in Malaysia as documented here List of Certification Authorities and Recognition.
You may also obtain the digital signature sample from this link:
• UBL 2.1 Invoice Sample XML with Signature: https://sdk.myinvois.hasil.gov.my/files/one-doc-signed.xml
• UBL 2.1 Invoice Sample JSON with Signature: https://sdk.myinvois.hasil.gov.my/files/sample-ul-invoice-2.1-signed.min.json
Disclaimer: The sample JSON file is for digital signature illustration purposes only. Taxpayers are advised to consult local laws and regulations for guidance on digital signature implementation.
Which version of Document Types should taxpayers use to test and validate Digital Signature in the Sandbox environment?
Both versions v1.0 and v1.1 are available on the Sandbox. Taxpayers interested in testing and validating Digital Signature should use v1.1 for their Sandbox testing.
What are the key differences between version 1.1 and version 1.0?
Digital signature can only be validated in version 1.1.
Why was version 1.1 introduced?
To allow taxpayers to test the digital signature validation after submitting invoice in the Sandbox environment.
Do I need to submit the documents in version 1.0 and version 1.1?
Taxpayers are given the option to decide to submit documents in version 1.0 or version 1.1 depending on testing requirements. If taxpayers intend to test digital signature, it is recommended to submit using version 1.1. Version 1.0 is available for submission of documents without digital signature validation.
Is the submission using Document Version 1.0 allowed to be used for submission on 1 August 2024 onwards?
Taxpayers may submit documents using document version 1.0 without the requirement for digital signature validation until such time as the Lembaga Hasil Dalam Negeri Malaysia (LHDNM) issues an official notice concerning the retirement of version 1.0. Nonetheless, it is strongly recommended that taxpayers adopt version 1.1, which incorporates digital signature validation, to ensure the authenticity of the supplier’s identity.
How do I ensure the digitally signed document created is valid?
You can refer to the Signature Validation section in the Signature page https://sdk.myinvois.hasil.gov.my/signature/ on how to digitally sign the document, adhering to the digital signing creation requirements and validation rules for signature.
How can I get a valid digital certificate for my organisation?
The certificates must be issued by the certificates authority as listed in the MCMC website at https://www.mcmc.gov.my/en/sectors/digital-signature/list-of-licensees.
What type of digital certificate do I need to procure?
Both Soft and Roaming certificates can be used for MyInvois purpose, depending on your system configuration. Soft certificate is installed in local machine, while Roaming certificate is installed in Server.
For companies that have subsidiaries, does digital certificate need to be registered for each subsidiary?
Subsidiaries have the option to independently procure their own digital certificates for document submission. Alternatively, the headquarters can designate one subsidiary as an intermediary tasked with registering and managing digital certificates for the entire organization, including all subsidiaries.
As a service provider, what type of certificate do I need to procure to submit documents that are digitally signed?
The service provider can procure either Soft or Roaming certificates for MyInvois purpose, depending on the system configuration. Soft certificate is installed in local machine, while Roaming certificate is installed in Server.
As a service provider, do I need a different certificate for each customer I am representing?
No. Service providers can use their own certificate to submit document for all their customers.
Which digital certificate is required for document submission via API: an individual’s or an organisation’s?”
For submission through API, an organisation digital certificate is required.
What are the best practices to integrate with API?
Refer to this page for more information Intergration-practices.
What is the Call Limit for each API?
The rate limiting functionality implementation is using the standard HTTP rate limiting headers. The Call Limit is based on the anticipated load and usage patterns of the API. Hence, the caller should handle the rate limiting headers that are returned to them by the API and retry the call as per these headers. The header would specify the current number of calls that are rate limited and the time period the caller should wait before they make the next call. Please, refer back Standard Headers Parameters to standard rate limiting headers definition.
How to get validation link and generate QR code?
The QR code (quick response code) can be generated from the validation link using any QR code generator. The validation link can be created using the format below:
{envbaseurl}/uuid-of-document/share/longid
The {envbaseurl} will need to be replaced with e-Invoice portal Base URL. The UUID and long ID can both be obtained as return parameters for Get Submission, Get Document or Get Document Detail API.