Do I need a digital certificate for Malaysia e-invoicing?

No. InvoisX handles digital signing with our certificate. You don't need to obtain or manage certificates from MCMC-listed Certificate Authorities.

Do I need to learn UBL 2.1 for LHDN e-invoicing?

No. Send simple JSON via our REST API, and we convert it to LHDN-compliant UBL format automatically. No XML knowledge required.

What about the 50+ required fields for LHDN e-invoicing?

We auto-fill most fields with smart defaults. You only need to provide your line items with quantities and prices - we handle the rest.

How does InvoisX handle LHDN token expiration?

We manage LHDN authentication internally. Your API token from InvoisX never expires unless you explicitly revoke it.

What happens when LHDN changes their e-invoicing spec?

We update our backend to comply with new LHDN requirements. Your integration code stays the same - no changes needed on your end.

Which programming languages are supported by InvoisX?

Any language that can make HTTP requests. We provide examples in PHP, Node.js, Python, Java, C#, and more. It's just a REST API.

What if I need full control over calculations?

Set autoCalculate to false and send every field yourself. We support all LHDN required and optional fields. Use auto-calculate for convenience, or disable it for precision - your choice.

Document Types

InvoisX supports all LHDN document types. This guide covers the different document types and when to use them.

Setup

Before using the examples below, set up your HTTP client:

javascript

const API_URL = 'https://invoisx.com/api/v1';
const API_TOKEN = 'your-api-token';

async function api(method, endpoint, data = null) {
  const response = await fetch(`${API_URL}${endpoint}`, {
    method,
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Accept': 'application/json',
      'Content-Type': 'application/json',
    },
    body: data ? JSON.stringify(data) : null,
  });
  return response.json();
}

python

import requests

API_URL = 'https://invoisx.com/api/v1'
API_TOKEN = 'your-api-token'

def api(method, endpoint, data=None):
    response = requests.request(
        method,
        f'{API_URL}{endpoint}',
        headers={
            'Authorization': f'Bearer {API_TOKEN}',
            'Accept': 'application/json',
        },
        json=data
    )
    return response.json()

php

use Illuminate\Support\Facades\Http;

$api = Http::withToken('your-api-token')
    ->accept('application/json')
    ->baseUrl('https://invoisx.com/api/v1');

php

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://invoisx.com/api/v1/',
    'headers' => [
        'Authorization' => 'Bearer your-api-token',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ]
]);

java

import java.net.http.*;
import java.net.URI;

var client = HttpClient.newHttpClient();
var API_URL = "https://invoisx.com/api/v1";
var API_TOKEN = "your-api-token";

HttpResponse<String> api(String method, String endpoint, String jsonBody) throws Exception {
    var builder = HttpRequest.newBuilder()
        .uri(URI.create(API_URL + endpoint))
        .header("Authorization", "Bearer " + API_TOKEN)
        .header("Accept", "application/json")
        .header("Content-Type", "application/json");

    if (jsonBody != null) {
        builder.method(method, HttpRequest.BodyPublishers.ofString(jsonBody));
    } else {
        builder.method(method, HttpRequest.BodyPublishers.noBody());
    }
    return client.send(builder.build(), HttpResponse.BodyHandlers.ofString());
}

csharp

using System.Net.Http;
using System.Text;
using System.Text.Json;

var client = new HttpClient {
    BaseAddress = new Uri("https://invoisx.com/api/v1")
};
client.DefaultRequestHeaders.Add("Authorization", "Bearer your-api-token");
client.DefaultRequestHeaders.Add("Accept", "application/json");

Document Type Overview

Type	Endpoint	Required Field	Use Case
Invoice	`/invoices`	`buyerId`	Standard sales invoice
Credit Note	`/credit-notes`	`buyerId`	Reduce amount owed
Debit Note	`/debit-notes`	`buyerId`	Increase amount owed
Refund Note	`/refund-notes`	`buyerId`	Full refund
Consolidated Invoice	`/consolidated-invoices`	`buyerId`	Multiple transactions
Self-Billed Invoice	`/self-billed-invoices`	`onBehalfSellerId`	Buyer issues invoice
Self-Billed Credit Note	`/self-billed-credit-notes`	`onBehalfSellerId`	Self-billed credit
Self-Billed Debit Note	`/self-billed-debit-notes`	`onBehalfSellerId`	Self-billed debit
Self-Billed Refund Note	`/self-billed-refund-notes`	`onBehalfSellerId`	Self-billed refund

Credit Notes

Credit notes reduce the amount owed by referencing an original invoice.

Creating a Credit Note

Credit notes require documentReferences linking to the original invoice:

javascript

const creditNote = await api('POST', '/credit-notes', {
  buyerId: 'buyer-uuid',
  invoiceSerialNumber: 'CN-2024-001',
  currencyCode: 'MYR',
  autoCalculate: true,
  documentReferences: [
    {
      referenceNumber: 'INV-2024-001',
      uuid: 'original-invoice-lhdn-uuid'  // LHDN document UUID
    }
  ],
  invoiceLines: [
    {
      classifications: ['001'],
      productDescription: 'Returned Item - Credit',
      quantity: 1,
      unitCode: 'H87',
      unitPrice: 100.00,
      invoiceLineTaxes: [
        { taxType: '01', taxRate: 8 }
      ]
    }
  ]
});

python

credit_note = api('POST', '/credit-notes', {
    'buyerId': 'buyer-uuid',
    'invoiceSerialNumber': 'CN-2024-001',
    'currencyCode': 'MYR',
    'autoCalculate': True,
    'documentReferences': [
        {
            'referenceNumber': 'INV-2024-001',
            'uuid': 'original-invoice-lhdn-uuid'
        }
    ],
    'invoiceLines': [
        {
            'classifications': ['001'],
            'productDescription': 'Returned Item - Credit',
            'quantity': 1,
            'unitCode': 'H87',
            'unitPrice': 100.00,
            'invoiceLineTaxes': [
                {'taxType': '01', 'taxRate': 8}
            ]
        }
    ]
})

php

$creditNote = $api->post('/credit-notes', [
    'buyerId' => 'buyer-uuid',
    'invoiceSerialNumber' => 'CN-2024-001',
    'currencyCode' => 'MYR',
    'autoCalculate' => true,
    'documentReferences' => [
        [
            'referenceNumber' => 'INV-2024-001',
            'uuid' => 'original-invoice-lhdn-uuid'
        ]
    ],
    'invoiceLines' => [
        [
            'classifications' => ['001'],
            'productDescription' => 'Returned Item - Credit',
            'quantity' => 1,
            'unitCode' => 'H87',
            'unitPrice' => 100.00,
            'invoiceLineTaxes' => [
                ['taxType' => '01', 'taxRate' => 8]
            ]
        ]
    ]
]);

php

$response = $client->post('credit-notes', ['json' => [
    'buyerId' => 'buyer-uuid',
    'invoiceSerialNumber' => 'CN-2024-001',
    'currencyCode' => 'MYR',
    'autoCalculate' => true,
    'documentReferences' => [
        [
            'referenceNumber' => 'INV-2024-001',
            'uuid' => 'original-invoice-lhdn-uuid'
        ]
    ],
    'invoiceLines' => [
        [
            'classifications' => ['001'],
            'productDescription' => 'Returned Item - Credit',
            'quantity' => 1,
            'unitCode' => 'H87',
            'unitPrice' => 100.00,
            'invoiceLineTaxes' => [
                ['taxType' => '01', 'taxRate' => 8]
            ]
        ]
    ]
]]);
$creditNote = json_decode($response->getBody(), true);

java

var json = """
    {
        "buyerId": "buyer-uuid",
        "invoiceSerialNumber": "CN-2024-001",
        "currencyCode": "MYR",
        "autoCalculate": true,
        "documentReferences": [
            {
                "referenceNumber": "INV-2024-001",
                "uuid": "original-invoice-lhdn-uuid"
            }
        ],
        "invoiceLines": [
            {
                "classifications": ["001"],
                "productDescription": "Returned Item - Credit",
                "quantity": 1,
                "unitCode": "H87",
                "unitPrice": 100.00,
                "invoiceLineTaxes": [
                    {"taxType": "01", "taxRate": 8}
                ]
            }
        ]
    }""";
var response = api("POST", "/credit-notes", json);

csharp

var creditNote = new {
    buyerId = "buyer-uuid",
    invoiceSerialNumber = "CN-2024-001",
    currencyCode = "MYR",
    autoCalculate = true,
    documentReferences = new[] {
        new {
            referenceNumber = "INV-2024-001",
            uuid = "original-invoice-lhdn-uuid"
        }
    },
    invoiceLines = new[] {
        new {
            classifications = new[] { "001" },
            productDescription = "Returned Item - Credit",
            quantity = 1,
            unitCode = "H87",
            unitPrice = 100.00,
            invoiceLineTaxes = new[] {
                new { taxType = "01", taxRate = 8 }
            }
        }
    }
};
var response = await client.PostAsJsonAsync("/credit-notes", creditNote);

Pre-E-Invoicing Credit Notes

For credit notes referencing invoices issued before LHDN e-invoicing began:

json

{
  "buyerId": "buyer-uuid",
  "invoiceSerialNumber": "CN-PRE-001",
  "isPreEinvoicing": true,
  "documentReferences": [
    {
      "referenceNumber": "OLD-INV-001"
    }
  ],
  "invoiceLines": [/* ... */]
}

TIP

Setting isPreEinvoicing: true allows submission without an LHDN UUID reference.

Debit Notes

Debit notes increase the amount owed:

javascript

const debitNote = await api('POST', '/debit-notes', {
  buyerId: 'buyer-uuid',
  invoiceSerialNumber: 'DN-2024-001',
  currencyCode: 'MYR',
  autoCalculate: true,
  documentReferences: [
    {
      referenceNumber: 'INV-2024-001',
      uuid: 'original-invoice-lhdn-uuid'
    }
  ],
  invoiceLines: [
    {
      classifications: ['001'],
      productDescription: 'Additional Charges',
      quantity: 1,
      unitCode: 'H87',
      unitPrice: 50.00,
      invoiceLineTaxes: [
        { taxType: '01', taxRate: 8 }
      ]
    }
  ]
});

python

debit_note = api('POST', '/debit-notes', {
    'buyerId': 'buyer-uuid',
    'invoiceSerialNumber': 'DN-2024-001',
    'currencyCode': 'MYR',
    'autoCalculate': True,
    'documentReferences': [
        {
            'referenceNumber': 'INV-2024-001',
            'uuid': 'original-invoice-lhdn-uuid'
        }
    ],
    'invoiceLines': [
        {
            'classifications': ['001'],
            'productDescription': 'Additional Charges',
            'quantity': 1,
            'unitCode': 'H87',
            'unitPrice': 50.00,
            'invoiceLineTaxes': [
                {'taxType': '01', 'taxRate': 8}
            ]
        }
    ]
})

php

$debitNote = $api->post('/debit-notes', [
    'buyerId' => 'buyer-uuid',
    'invoiceSerialNumber' => 'DN-2024-001',
    'currencyCode' => 'MYR',
    'autoCalculate' => true,
    'documentReferences' => [
        [
            'referenceNumber' => 'INV-2024-001',
            'uuid' => 'original-invoice-lhdn-uuid'
        ]
    ],
    'invoiceLines' => [
        [
            'classifications' => ['001'],
            'productDescription' => 'Additional Charges',
            'quantity' => 1,
            'unitCode' => 'H87',
            'unitPrice' => 50.00,
            'invoiceLineTaxes' => [
                ['taxType' => '01', 'taxRate' => 8]
            ]
        ]
    ]
]);

php

$response = $client->post('debit-notes', ['json' => [
    'buyerId' => 'buyer-uuid',
    'invoiceSerialNumber' => 'DN-2024-001',
    'currencyCode' => 'MYR',
    'autoCalculate' => true,
    'documentReferences' => [
        [
            'referenceNumber' => 'INV-2024-001',
            'uuid' => 'original-invoice-lhdn-uuid'
        ]
    ],
    'invoiceLines' => [
        [
            'classifications' => ['001'],
            'productDescription' => 'Additional Charges',
            'quantity' => 1,
            'unitCode' => 'H87',
            'unitPrice' => 50.00,
            'invoiceLineTaxes' => [
                ['taxType' => '01', 'taxRate' => 8]
            ]
        ]
    ]
]]);
$debitNote = json_decode($response->getBody(), true);

java

var json = """
    {
        "buyerId": "buyer-uuid",
        "invoiceSerialNumber": "DN-2024-001",
        "currencyCode": "MYR",
        "autoCalculate": true,
        "documentReferences": [
            {
                "referenceNumber": "INV-2024-001",
                "uuid": "original-invoice-lhdn-uuid"
            }
        ],
        "invoiceLines": [
            {
                "classifications": ["001"],
                "productDescription": "Additional Charges",
                "quantity": 1,
                "unitCode": "H87",
                "unitPrice": 50.00,
                "invoiceLineTaxes": [
                    {"taxType": "01", "taxRate": 8}
                ]
            }
        ]
    }""";
var response = api("POST", "/debit-notes", json);

csharp

var debitNote = new {
    buyerId = "buyer-uuid",
    invoiceSerialNumber = "DN-2024-001",
    currencyCode = "MYR",
    autoCalculate = true,
    documentReferences = new[] {
        new {
            referenceNumber = "INV-2024-001",
            uuid = "original-invoice-lhdn-uuid"
        }
    },
    invoiceLines = new[] {
        new {
            classifications = new[] { "001" },
            productDescription = "Additional Charges",
            quantity = 1,
            unitCode = "H87",
            unitPrice = 50.00,
            invoiceLineTaxes = new[] {
                new { taxType = "01", taxRate = 8 }
            }
        }
    }
};
var response = await client.PostAsJsonAsync("/debit-notes", debitNote);

Refund Notes

Refund notes represent full refunds:

javascript

const refundNote = await api('POST', '/refund-notes', {
  buyerId: 'buyer-uuid',
  invoiceSerialNumber: 'RN-2024-001',
  currencyCode: 'MYR',
  autoCalculate: true,
  documentReferences: [
    {
      referenceNumber: 'INV-2024-001',
      uuid: 'original-invoice-lhdn-uuid'
    }
  ],
  invoiceLines: [
    {
      classifications: ['001'],
      productDescription: 'Full Refund',
      quantity: 1,
      unitCode: 'H87',
      unitPrice: 1000.00,
      invoiceLineTaxes: [
        { taxType: '01', taxRate: 8 }
      ]
    }
  ]
});

python

refund_note = api('POST', '/refund-notes', {
    'buyerId': 'buyer-uuid',
    'invoiceSerialNumber': 'RN-2024-001',
    'currencyCode': 'MYR',
    'autoCalculate': True,
    'documentReferences': [
        {
            'referenceNumber': 'INV-2024-001',
            'uuid': 'original-invoice-lhdn-uuid'
        }
    ],
    'invoiceLines': [
        {
            'classifications': ['001'],
            'productDescription': 'Full Refund',
            'quantity': 1,
            'unitCode': 'H87',
            'unitPrice': 1000.00,
            'invoiceLineTaxes': [
                {'taxType': '01', 'taxRate': 8}
            ]
        }
    ]
})

php

$refundNote = $api->post('/refund-notes', [
    'buyerId' => 'buyer-uuid',
    'invoiceSerialNumber' => 'RN-2024-001',
    'currencyCode' => 'MYR',
    'autoCalculate' => true,
    'documentReferences' => [
        [
            'referenceNumber' => 'INV-2024-001',
            'uuid' => 'original-invoice-lhdn-uuid'
        ]
    ],
    'invoiceLines' => [
        [
            'classifications' => ['001'],
            'productDescription' => 'Full Refund',
            'quantity' => 1,
            'unitCode' => 'H87',
            'unitPrice' => 1000.00,
            'invoiceLineTaxes' => [
                ['taxType' => '01', 'taxRate' => 8]
            ]
        ]
    ]
]);

php

$response = $client->post('refund-notes', ['json' => [
    'buyerId' => 'buyer-uuid',
    'invoiceSerialNumber' => 'RN-2024-001',
    'currencyCode' => 'MYR',
    'autoCalculate' => true,
    'documentReferences' => [
        [
            'referenceNumber' => 'INV-2024-001',
            'uuid' => 'original-invoice-lhdn-uuid'
        ]
    ],
    'invoiceLines' => [
        [
            'classifications' => ['001'],
            'productDescription' => 'Full Refund',
            'quantity' => 1,
            'unitCode' => 'H87',
            'unitPrice' => 1000.00,
            'invoiceLineTaxes' => [
                ['taxType' => '01', 'taxRate' => 8]
            ]
        ]
    ]
]]);
$refundNote = json_decode($response->getBody(), true);

java

var json = """
    {
        "buyerId": "buyer-uuid",
        "invoiceSerialNumber": "RN-2024-001",
        "currencyCode": "MYR",
        "autoCalculate": true,
        "documentReferences": [
            {
                "referenceNumber": "INV-2024-001",
                "uuid": "original-invoice-lhdn-uuid"
            }
        ],
        "invoiceLines": [
            {
                "classifications": ["001"],
                "productDescription": "Full Refund",
                "quantity": 1,
                "unitCode": "H87",
                "unitPrice": 1000.00,
                "invoiceLineTaxes": [
                    {"taxType": "01", "taxRate": 8}
                ]
            }
        ]
    }""";
var response = api("POST", "/refund-notes", json);

csharp

var refundNote = new {
    buyerId = "buyer-uuid",
    invoiceSerialNumber = "RN-2024-001",
    currencyCode = "MYR",
    autoCalculate = true,
    documentReferences = new[] {
        new {
            referenceNumber = "INV-2024-001",
            uuid = "original-invoice-lhdn-uuid"
        }
    },
    invoiceLines = new[] {
        new {
            classifications = new[] { "001" },
            productDescription = "Full Refund",
            quantity = 1,
            unitCode = "H87",
            unitPrice = 1000.00,
            invoiceLineTaxes = new[] {
                new { taxType = "01", taxRate = 8 }
            }
        }
    }
};
var response = await client.PostAsJsonAsync("/refund-notes", refundNote);

Consolidated Invoices

Consolidated invoices combine multiple transactions:

javascript

const consolidated = await api('POST', '/consolidated-invoices', {
  buyerId: 'buyer-uuid',
  invoiceSerialNumber: 'CI-2024-001',
  currencyCode: 'MYR',
  autoCalculate: true,
  invoiceLines: [
    {
      classifications: ['001'],
      productDescription: 'Item 1 - Multiple Purchases',
      quantity: 10,
      unitCode: 'H87',
      unitPrice: 50.00,
      invoiceLineTaxes: [
        { taxType: '01', taxRate: 8 }
      ]
    },
    {
      classifications: ['002'],
      productDescription: 'Item 2 - Multiple Purchases',
      quantity: 5,
      unitCode: 'H87',
      unitPrice: 100.00,
      invoiceLineTaxes: [
        { taxType: '01', taxRate: 8 }
      ]
    }
  ]
});

python

consolidated = api('POST', '/consolidated-invoices', {
    'buyerId': 'buyer-uuid',
    'invoiceSerialNumber': 'CI-2024-001',
    'currencyCode': 'MYR',
    'autoCalculate': True,
    'invoiceLines': [
        {
            'classifications': ['001'],
            'productDescription': 'Item 1 - Multiple Purchases',
            'quantity': 10,
            'unitCode': 'H87',
            'unitPrice': 50.00,
            'invoiceLineTaxes': [
                {'taxType': '01', 'taxRate': 8}
            ]
        },
        {
            'classifications': ['002'],
            'productDescription': 'Item 2 - Multiple Purchases',
            'quantity': 5,
            'unitCode': 'H87',
            'unitPrice': 100.00,
            'invoiceLineTaxes': [
                {'taxType': '01', 'taxRate': 8}
            ]
        }
    ]
})

php

$consolidated = $api->post('/consolidated-invoices', [
    'buyerId' => 'buyer-uuid',
    'invoiceSerialNumber' => 'CI-2024-001',
    'currencyCode' => 'MYR',
    'autoCalculate' => true,
    'invoiceLines' => [
        [
            'classifications' => ['001'],
            'productDescription' => 'Item 1 - Multiple Purchases',
            'quantity' => 10,
            'unitCode' => 'H87',
            'unitPrice' => 50.00,
            'invoiceLineTaxes' => [
                ['taxType' => '01', 'taxRate' => 8]
            ]
        ],
        [
            'classifications' => ['002'],
            'productDescription' => 'Item 2 - Multiple Purchases',
            'quantity' => 5,
            'unitCode' => 'H87',
            'unitPrice' => 100.00,
            'invoiceLineTaxes' => [
                ['taxType' => '01', 'taxRate' => 8]
            ]
        ]
    ]
]);

php

$response = $client->post('consolidated-invoices', ['json' => [
    'buyerId' => 'buyer-uuid',
    'invoiceSerialNumber' => 'CI-2024-001',
    'currencyCode' => 'MYR',
    'autoCalculate' => true,
    'invoiceLines' => [
        [
            'classifications' => ['001'],
            'productDescription' => 'Item 1 - Multiple Purchases',
            'quantity' => 10,
            'unitCode' => 'H87',
            'unitPrice' => 50.00,
            'invoiceLineTaxes' => [
                ['taxType' => '01', 'taxRate' => 8]
            ]
        ],
        [
            'classifications' => ['002'],
            'productDescription' => 'Item 2 - Multiple Purchases',
            'quantity' => 5,
            'unitCode' => 'H87',
            'unitPrice' => 100.00,
            'invoiceLineTaxes' => [
                ['taxType' => '01', 'taxRate' => 8]
            ]
        ]
    ]
]]);
$consolidated = json_decode($response->getBody(), true);

java

var json = """
    {
        "buyerId": "buyer-uuid",
        "invoiceSerialNumber": "CI-2024-001",
        "currencyCode": "MYR",
        "autoCalculate": true,
        "invoiceLines": [
            {
                "classifications": ["001"],
                "productDescription": "Item 1 - Multiple Purchases",
                "quantity": 10,
                "unitCode": "H87",
                "unitPrice": 50.00,
                "invoiceLineTaxes": [
                    {"taxType": "01", "taxRate": 8}
                ]
            },
            {
                "classifications": ["002"],
                "productDescription": "Item 2 - Multiple Purchases",
                "quantity": 5,
                "unitCode": "H87",
                "unitPrice": 100.00,
                "invoiceLineTaxes": [
                    {"taxType": "01", "taxRate": 8}
                ]
            }
        ]
    }""";
var response = api("POST", "/consolidated-invoices", json);

csharp

var consolidated = new {
    buyerId = "buyer-uuid",
    invoiceSerialNumber = "CI-2024-001",
    currencyCode = "MYR",
    autoCalculate = true,
    invoiceLines = new[] {
        new {
            classifications = new[] { "001" },
            productDescription = "Item 1 - Multiple Purchases",
            quantity = 10,
            unitCode = "H87",
            unitPrice = 50.00,
            invoiceLineTaxes = new[] {
                new { taxType = "01", taxRate = 8 }
            }
        },
        new {
            classifications = new[] { "002" },
            productDescription = "Item 2 - Multiple Purchases",
            quantity = 5,
            unitCode = "H87",
            unitPrice = 100.00,
            invoiceLineTaxes = new[] {
                new { taxType = "01", taxRate = 8 }
            }
        }
    }
};
var response = await client.PostAsJsonAsync("/consolidated-invoices", consolidated);

Document References

For credit notes, debit notes, and refund notes:

Field	Type	Required	Description
`referenceNumber`	string	Yes	Original invoice number
`uuid`	string	No*	LHDN document UUID

*Required unless isPreEinvoicing: true

Document Operations

All document types share the same operations:

Validate

POST /documents/{id}/validate

Submit

POST /documents/{id}/submit

Check Status

GET /documents/{id}/status

Get QR Code

GET /documents/{id}/qr

Get PDF

GET /documents/{id}/pdf

Next Steps

Self-Billed Documents - Issue invoices on behalf of suppliers
Validation - Validate before submission
Submission - Submit to LHDN

Document Types ​

Setup ​

Document Type Overview ​

Credit Notes ​

Creating a Credit Note ​

Pre-E-Invoicing Credit Notes ​

Debit Notes ​

Refund Notes ​

Consolidated Invoices ​

Document References ​

Document Operations ​

Validate ​

Submit ​

Check Status ​

Get QR Code ​

Get PDF ​

Next Steps ​

Document Types

Setup

Document Type Overview

Credit Notes

Creating a Credit Note

Pre-E-Invoicing Credit Notes

Debit Notes

Refund Notes

Consolidated Invoices

Document References

Document Operations

Validate

Submit

Check Status

Get QR Code

Get PDF

Next Steps