Skip to navigation
V2E Invoice

Import Malaysia E-Invoice

View as Markdown

Import a Malaysia e-invoice document into a Staple Queue in JSON format. Staple will create a document (docId) and submit it to LHDN MyInvois asynchronously.

This endpoint supports all MyInvois document types, including self-billed types.

Endpoint

POST /v2/einvoice/malaysia/queue/{queueId}

Request Headers

AttributeTypeOptionDescription
x-api-keyStringRequiredA unique string
AuthorizationStringRequiredBearer token

Content-Type: application/json
Accept: application/json

Path Parameter

AttributeTypeOptionDescription
queueIdStringRequiredTarget queue ID

Supported Document Types (docType)

docType determines the business scenario. Allowed values:

docTypeDescription
invoiceCommercial document issued by Supplier to Buyer.
credit_noteIssued by Supplier to reduce the value of a previously issued e-Invoice (no money returned to Buyer).
debit_noteIssued by Supplier to indicate additional charges on a previously issued e-Invoice.
refund_noteIssued by Supplier to confirm refund of Buyer’s payment (money returned to Buyer).
self_billed_invoiceIssued by Buyer (instead of Supplier) in allowed self-billing scenarios.
self_billed_credit_noteIssued by Buyer to reduce value of a previously issued self-billed e-Invoice.
self_billed_debit_noteIssued by Buyer to indicate additional charges on a previously issued self-billed e-Invoice.
self_billed_refund_noteIssued by Buyer to confirm refund payment (money returned from Supplier to Buyer).

Request Payload (JSON)

A single endpoint supports all docType values above.

Top-level Fields

FieldTypeRequiredDescription
docTypeString✅One of the supported document types listed above.
docNumberString✅Document number (Invoice No / Credit Note No / etc.). Used for tracking and de-duplication.
issueDateString (YYYY-MM-DD)✅Issue date.
issueTimeString (HH:mm:ssZ)✅Issue time. Example: 09:44:25Z.
currencyString✅ISO 4217 currency code (e.g. MYR).
fxRateNumberOptionalForeign exchange rate. Use 1.0 for MYR documents when no conversion is needed.
supplierObject✅Supplier / issuer party.
buyerObject✅Buyer party.
linesArray✅Line items (min 1).
totalsObject✅Totals (must reconcile with lines).
referenceObjectOptionalRequired for adjustment documents (see Reference Rules).
reasonStringOptionalRecommended for adjustment documents (credit/debit/refund) and audit trail.

Sample Payload (Invoice)

Paste this into Postman Body.

{
  "docType": "invoice",
  "docNumber": "INV-2026-0001",
  "issueDate": "2026-03-23",
  "issueTime": "09:44:25Z",
  "currency": "MYR",
  "fxRate": 1.0,
  "supplier": {
    "name": "Seller Sdn Bhd",
    "tin": "IG59605712010",
    "registrationType": "PASSPORT",
    "registrationNo": "RA2052854",
    "msicCode": "85494",
    "address": {
      "line1": "1 Jalan Example",
      "city": "Kuala Lumpur",
      "stateCode": "14",
      "postcode": "50000",
      "country": "MYS"
    },
    "contact": {
      "telephone": "+60123456789"
    }
  },
  "buyer": {
    "name": "Buyer Sdn Bhd",
    "tin": "C59584904000",
    "registrationType": "BRN",
    "registrationNo": "202401040495",
    "address": {
      "line1": "2 Jalan Example",
      "city": "Kuala Lumpur",
      "stateCode": "14",
      "postcode": "50000",
      "country": "MYS"
    },
    "contact": {
      "telephone": "+60165537256"
    }
  },
  "lines": [
    {
      "lineNo": 1,
      "description": "Consulting service",
      "quantity": 1,
      "unitPrice": 100,
      "amount": 100,
      "amountExclTax": 100,
      "classifications": [
        {
          "code": "003"
        }
      ]
    },
    {
      "lineNo": 2,
      "description": "Non-taxable item",
      "quantity": 1,
      "uom": "EA",
      "unitPrice": 50,
      "amount": 50,
      "amountExclTax": 50,
      "classifications": [
        {
          "code": "003"
        }
      ],
      "taxes": [
        {
          "type": "NOT_APPLICABLE",
          "rate": 0,
          "amount": 0
        }
      ]
    }
  ],
  "totals": {
    "totalExclTax": 150,
    "totalInclTax": 168,
    "taxTotal": 18,
    "payableAmount": 168
  }
}

Reference Rules (VERY IMPORTANT)

Some document types must reference an earlier document.

Supplier-issued adjustments (reference original invoice)

When docType is one of:

  • credit_note

  • debit_note

  • refund_note

reference.originalInvoiceCodeNumber is required and must point to the original invoice docNumber / code number used by your integration.

Buyer-issued (self-billed) adjustments (reference original self_billed_invoice)

When docType is one of:

  • self_billed_credit_note

  • self_billed_debit_note

  • self_billed_refund_note

reference.originalInvoiceCodeNumber is required and must point to the original self_billed_invoice docNumber / code number used by your integration.

Reference Object

FieldTypeRequiredDescription
reference.originalInvoiceCodeNumberString✅ (when applicable)The original invoice/self-billed invoice code number being adjusted.

Example:

"reference": {
  "originalInvoiceCodeNumber": "INV-2026-0001"
}

Party Objects (supplier, buyer)

FieldTypeRequiredDescription
nameString✅Legal/trade name.
tinString✅Supplier TIN is required. Buyer TIN may be required depending on scenario.
registrationTypeString✅Registration identifier type, e.g. BRN, PASSPORT.
registrationNoString✅Registration number / identity number.
msicCodeStringConditionalBusiness classification code. Commonly provided on supplier.
addressObject✅Address object.
contactObject✅Contact object.

Address Object (recommended fields): line1, city, stateCode, postcode, country
Contact Object (recommended fields): telephone

Self-billed documents: Buyer is the issuer in business terms, but this API keeps supplier and buyer fields consistent. Staple validates and maps parties according to docType.

Line Items (lines[])

FieldTypeRequiredDescription
lineNoInteger✅Line sequence number (starting from 1).
descriptionString✅Item/service description.
quantityNumber✅Quantity.
uomStringOptionalUnit of measure (e.g. EA).
unitPriceNumber✅Unit price (non-negative).
amountNumberOptionalGross line amount before or alongside tax calculation, depending on integration flow.
amountExclTaxNumber✅Line amount excluding tax. Recommended to use negative amounts for credit_note and refund_note.
classificationsArray✅Example: [{"code": "003"}]
taxesArray✅Line-level taxes array (see Tax section).

Totals (totals)

FieldTypeRequiredDescription
totalExclTaxNumber✅Sum of lines[].amountExclTax.
totalInclTaxNumber✅Final total including tax.
taxTotalNumber✅Total tax amount across all lines.
payableAmountNumber✅Final payable amount. Usually matches totalInclTax.

Tax

Tax is represented at line-level under lines[].taxes.

Tax Object (taxes[])

FieldTypeRequiredDescription
typeString✅Tax category (see allowed values).
rateNumber✅Tax rate in percentage (e.g. 8.0).
amountNumber✅Tax amount for the line. May be negative for credit/refund documents.

Allowed Values for taxes[].type

TypeMeaning
SALES_TAXSales Tax
SERVICE_TAXService Tax
TOURISM_TAXTourism Tax
HIGH_VALUE_GOODS_TAXHigh-Value Goods Tax
LOW_VALUE_GOODS_TAXSales Tax on Low Value Goods
NOT_APPLICABLENo tax applies
EXEMPTTax exempt

Do not use ambiguous values like SST. Choose SALES_TAX or SERVICE_TAX explicitly.

To keep adjustments unambiguous:

  • credit_note: use negative amounts for lines[].amountExclTax, lines[].taxes[].amount, and totals.

  • refund_note: use negative amounts when reducing original invoice value and confirming money returned to Buyer.

  • debit_note: use positive amounts (additional charges).

Staple will validate totals consistency.

Response (Success)

The response confirms the document was queued in Staple. Use docId and trackingUrl to check ongoing status.

Example

{
  "requestId": "c86fdc72-51d7-4572-9e67-d11101bc3e29",
  "queueId": 4520,
  "docId": 242069,
  "docType": "invoice",
  "docNumber": "INV-2026-0001",
  "message": "Document queued for processing. Use docId to track submission status.",
  "trackingUrl": "/v2/einvoice/malaysia/status/242069",
  "myInvois": {
    "submissionId": "9EJDZFB2WJ967NZ5AXSXNMMK10",
    "uuid": "7ZPFV97R3VPY3HWGAXSXNMMK10"
  }
}

Response Field Notes

  • requestId: Request trace ID.

  • queueId: Queue used for import.

  • docId: Staple document ID created in the queue.

  • docType: Imported document type.

  • docNumber: Imported document number.

  • message: Human-readable processing message.

  • trackingUrl: Internal status endpoint for this document.

  • myInvois.submissionId: MyInvois submission batch ID.

  • myInvois.uuid: MyInvois document UUID.

myInvois is present only when Staple already has MyInvois submission details available at response time.
If processing later fails, or MyInvois details are not ready yet, the response may still return docId without myInvois.
In that case, check the actual processing result via:
GET /v2/einvoice/malaysia/status/{docId}

Error / Status Handling

This endpoint is asynchronous.
A successful import request can still return a normal queued response first, while the actual Malaysia e-invoice processing succeeds or fails later.

Important behavior

  • Do not assume failures will come back as HTTP errors from the import endpoint.

  • If processing fails after the document is queued, the response may simply not include myInvois.

  • When myInvois is missing, use docId to call the status endpoint and inspect the real outcome.

Example follow-up check

GET /v2/einvoice/malaysia/status/242069

Use this endpoint to check whether the document was submitted, validated, rejected, or failed during later processing.

Practical rule

  • Import response has docId + myInvois → MyInvois submission details are already available.

  • Import response has docId but no myInvois → do not treat it as HTTP failure; call /v2/einvoice/malaysia/status/{docId}.

Authentication

x-api-keystring
API key issued by Staple.
AuthorizationBearer
JWT obtained from the login endpoint.

Request

This endpoint expects an object.
docTypestringOptional
docNumberstringOptional
issueDatestringOptional
issueTimestringOptional
currencystringOptional
fxRateintegerOptional
supplierobjectOptional
buyerobjectOptional
lineslist of objectsOptional
taxTotalslist of objectsOptional
totalsobjectOptional

Response

OK