ClearTax / LHDN E-Invoicing

CityScreen Deals submits invoices for e-invoicing validation through ClearTax, which relays them to Malaysia’s LHDN tax authority via the MyInvois platform. The interface labels this integration "ClearTax integration", and the submission target is the government’s MyInvois system.

This is a one-way outbound submission with status polling. Deals sends invoice data to ClearTax, then polls for validation results, either on request with Check status or automatically in the background.

This integration is tenant-specific. It may not appear in your interface if it is not enabled for your organization.

Setup

Two steps are required before invoices can be submitted.

1. Enter credentials

  1. Open Settings → Sync → ClearTax integration.

  2. Enter the ClearTax base URL and access token.

  3. Enable the integration and save.

2. Initialize the document-type mapping

  1. On the same ClearTax integration section, click Initialize.

  2. This one-time call creates and labels the document type that Deals uses for e-invoice export.

The Initialize action can only be run once. If it has already been completed, clicking it again returns an error (HTTP 409 Conflict). This is expected — it means initialization was already done.

The mapping itself — which internal document type represents the invoice to export — is configured once during setup and is not normally changed afterward.

Submitting an invoice

  1. Open Settings → ClearTax.

  2. Select the document you want to submit.

  3. Click Send.

Deals sends the document to ClearTax, which forwards it to LHDN for validation. A successful submission adds a success entry to the sync log. To resubmit a rejected invoice, correct the document in the normal document editing flow, then select it here and click Send again.

Business processes can also trigger submission automatically as part of a workflow — in that case, no manual action is needed.

Checking validation status

After submission, the invoice moves through validation at LHDN. To poll for the current status:

  1. On the Settings → ClearTax page, select the submitted document.

  2. Click Check status.

Check status also refreshes the status shown in the sync log.

When the provider returns a VALID status, Deals downloads the government QR code image, stores it as a file attachment on the document, and records the validation timestamp, UUID, and long ID.

Automatic status polling

Deals also re-checks the validation status of previously submitted invoices in the background. This runs independently of any manual action — you do not need to click Check status for every document.

Documents that have already reached a terminal status (valid, cancelled, or failed) are not re-checked.

The sync log

Every submission and status-check attempt is recorded in a log table on the Settings → ClearTax page.

Each log entry shows:

  • The document name or identifier.

  • The submission status (Success, Error, HTTP Error, or Info).

  • The ClearTax/LHDN validation status.

  • An error message, if any.

  • The date and time of the attempt.

The log is filterable by document and by status. The ClearTax log retains the full history of every attempt.

What to do when things go wrong

Each situation below says what to do.

An invoice reaches "Valid" status without a QR code

The provider can return a VALID status before its QR code image is ready.

What to do

Open the document on the ClearTax page and click Check status again. If the QR code is now available at the provider, Deals downloads and attaches it.

If the QR code is still missing after a successful status check, contact your CityScreen administrator — the provider may not have generated the QR code for this invoice.

Sum mismatches fail validation

An invoice can fail ClearTax/LHDN validation because its internal line-item totals do not reconcile with the overall sum. The provider rejects the submission and returns a validation error.

What to do

Read the error message in the sync log — it identifies which sums do not match. Correct the invoice’s amounts in the source document, then resubmit.

Cancellation

Whether an invoice can be cancelled after submission depends on its current status in the submission lifecycle. The option is offered when cancellation is possible, and invoices in the statuses Submitted, Validated, Reviewed and Shipped cannot be cancelled through the ClearTax integration.

Permissions

Configuring the ClearTax integration, sending documents, and checking status all require the Organization settings permission with update access. This is the same permission that governs other organization-level settings.

Viewing the sync log requires read access to the same permission.

See Roles & Permissions.