Step 1: Supplier Creates the Standard Business Document

Every invoice sent to Sovos must be part of a Standard Business Document (SBD). This document includes a Standard Business Document Header (SBDH) and a Sovos Document node, which includes a Sovos Canonical Invoice (SCI). To create the SBD, follow the detailed instructions in the SBDH, Sovos Document, and SCI pages.

Besides the SCI format, the payload can be also of Malaysian UBL 2.1 format. The structure of the Malaysian format is explained here.

Here is a list of supported e-Invoice types (InvoiceTypeCode):

• Invoice (01)

• Credit Note (02)

• Debit Note (03)

• Refund Note (04)

• Self-billed Invoice (11)

• Self-billed Credit Note (12)

• Self-billed Debit Note (13)

• Self-billed Refund Note (14)

Step 2: Supplier sends the SBD to Sovos

The supplier sends a POST request to the /documents endpoint. The request must include the following request body parameters:

Step 3: Sovos Maps the SCI into XML

Upon receiving the SCI file, Sovos maps it into the required XML format.

Step 4: Sovos validates the XML

Sovos performs schema validation based on the information provided by the Tax Authority. If there are errors in the document sent by the client, Sovos detects them instead of waiting for the Tax Authority's response.

Step 5: Sovos signs the XML

Sovos signs the file using the taxpayer's certificate, which generates the legalSigned attachment .

Step 6: Sovos batches the XMLs

After the XML file is signed, the request is placed into a batch before being transmitted to IRBM.

The batch is transmitted after one of the following limits is met:

Step 7: Sovos Transmits the XML

Sovos transmits the batch to the Tax Authority's e-Invoice system (IRBM).

Step 8: IRBM Processes the XML

The IRBM system proceeds to validate the schema documents and verify that business logic, signature, taxpayer information and duplicates are checkedbefore returning a success message or rejection message indicating IRBM has approved the document.

The XML file is then also made available for the Counterparty to retrieve, and potentially reject, within 72 hours. If the Counterparty rejects the invoice, it is still considered active until the Taxpayer cancels the invoice separately or issues a Credit note/Debit note. After 72 hours of issuance, the Counterparty can still reject out-of-band and thus it is not implicitly accepted just because 72 hours have passed without a rejection.

Consolidated invoices cannot be rejected by the Counterparty.

Step 9: IRBM Sends the Response to Sovos

After performing its services, the IRBM system sends the response to Sovos.

Step 10: Taxpayer Retrieves the Application Responses

It is highly recommended that clients configure their Application Response attachments as download links instead of base64 encoded data to avoid potential size limitations when retrieving responses. The default option is download links.

• Select download links to return a URL to access the file

• Use binary data to embed the file directly in base64 format

This configuration is available through our Professional Services team.

After sending document, youwill receive a JSON response message with an HTTP status code of 202 (asynchronous transaction). This means that the supplier must retrieve the application responses that become available during the transaction, which provide status information and also contain the signed XML encoded in Base64 when it's available. Additionally, the following details included in the response must be considered.

Clients have the option to retrieve application responses (notifications) in one of two ways:

The taxpayer can use the following Indirect Tax API endpoints to retrieve application responses:

• GET /notifications/MY

• GET /documents/MY/{documentId}/notifications

Step 11: Supplier Marks the Application Responses as Acknowledged

After retrieving application responses, the supplier must process them and mark them as acknowledged. This can be done by sending a PUT request to the /notifications/MY endpoint.

To make this request, set the following request body parameters:

PDF Generation

Sovos generates a PDF that contains the content of the invoice XML in a human-readable format along with the QR code. The QR code itself contains a public link to the invoice on the IRBM portal.

Archiving

Archiving can be done as a bundle, for example, as part of the Clearance flow, and is recommended for suppliers integrating with the Sovos solution for Malaysia for the first time. It can also be done separately, using an explicit API call that uses another archive. For more information on standalone archiving, see the eArchiving documentation page.

Bundled e-invoice archiving on the new platform is optional. Existing customers can choose to use their current solution and include e-Archiving.

Distribution

The invoice can be communicated to the Counterparty by Sovos or the taxpayer.

Error Handling

Customers need to adhere to the error handling principles outlined on the responses page.

In general, all error codes in the 400 range are client errors, so the customer needs to analyze them. After fixing the error, it's possible to resend the request. Error codes 408 and 429 are exceptions: in these cases, customers should wait at least 60 seconds before retrying. Error codes in the 500 range indicate server errors. See the HTTP status codes page for more information. When these errors occur, customers should resend the request following the guidance provided on the responses page, which also lists all error codes that the Indirect Tax API may return. This government web page contains documentation about the API that includes all the error codes and messages that can be returned, and can be used for error handling.

Step 1: Sovos Retrieves the Documents from the MY IRBM System

Sovos uses the buyer's credentials to authenticate with the MY IRBM system to collect the documents that have been made available (either in JSON or XML formats).

Step 2: Sovos Generates the PDF

Sovos generates a PDF from each document from IRBM and generates a notification. That includes the content of the QR code and the validation link for this document.

Step 3: Sovos Maps the Retrieved Document into SCI and Makes them Available

Sovos stores the retrieved documents, maps them to SCI, and makes them available for buyers to get. The PDF version of the documents is also made available.

Step 4: Sovos Distributes the PDF

Sovos can distribute the PDF via email to a configurable email address.

Step 5: Buyer Retrieves the Available Documents

It is highly recommended that clients configure their Application Response attachments as download links instead of base64 encoded data to avoid potential size limitations when retrieving responses. The default option is "download links".

• When using "download links" option, the response contains a URL from where the file can be downloaded.

• When using "binary data" option, the file itself is embedded in the response encoded in base64.

This configuration is available through our Professional Services team.

The buyer can use the following Indirect Tax API endpoint to retrieve application responses:

GET /notifications/MY

To complete a transaction, the buyer must retrieve the application responses until the transaction has finished. If the buyer has subscribed to all notifications, the transaction can generate different application responses, as shown in the table below:

Step 6: Buyer Acknowledges the Retrieved Documents

After retrieving the documents, the buyer must process them and mark them as acknowledged. This can be done by sending a PUT request to the /notifications/MY endpoint.

To make this request, set the following request body parameters:

Step 1: Buyer sends a POST Request to Sovos

The buyer sends a POST request to the /documents/MY/action endpoint.

To make this request, set the following request body parameters:

Step 2: Sovos transmits Request to IRBM

Sovos finds the corresponding document in the system and transmits the rejection request to IRBM.

Step 3: IRBM processes the Request

IRBM verifies that the 72-hour window has not passed since the original document was issued, and that the document can be rejected successfully.

Step 4: IRBM returns the Response

IRBM returns the success message, or the error message if the rejection could not be performed.

Step 5: Buyer retrieves the Application Responses

It is highly recommended that clients configure their Application Response attachments as download links instead of base64 encoded data to avoid potential size limitations when retrieving responses. The default option is "download links".

• When using "download links" option, the response contains a URL from where the file can be downloaded.

• When using "binary data" option, the file itself is embedded in the response encoded in base64.

This configuration is available through our Professional Services team.

As a response to the initial sending of the document, the client will receive a JSON response message with an HTTP status code of 202 (asynchronous transaction). This means that the supplier must retrieve the application responses that become available during the transaction, which provide status information.

Clients have the option to retrieve application responses (notifications) in one of two ways:

Fetch everything in one single response (notification)

This means, when polling for responses, Sovos will only return one final notification with SCICloudStatusCode 209 that contains all the relevant attachments/data. Detailed description follows.

Fetch multiple responses (notifications) containing different information

In this case, when polling for responses, Sovos will return multiple notifications with different SCICloudStatusCode values containing different attachments/data until the final one (with status 209) is returned. Detailed description follows.

Step 6: Buyer marks the Application Responses as Acknowledged

After retrieving application responses, the buyer must process them and mark them as acknowledged. This can be done by sending a PUT request to the /notifications/MY endpoint.

To make this request, set the following request body parameters:

Error Handling

Customers need to adhere to the error handling principles outlined on the responses page.

In general, all error codes in the 400 range are client errors, so the customer needs to analyze them. After fixing the error, it's possible to resend the request. Error codes 408 and 429 are exceptions: in these cases, customers should wait at least 60 seconds before retrying. Error codes in the 500 range indicate server errors. When these occur, customers should resend the request following the guidance provided on the responses page, which also lists all error codes that the Indirect Tax API may return. This government web page contains documentation about the API that includes all the error codes and messages that can be returned, and can be used for error handling.

Errors coming from the IRBM system will be shown in the application response. This means that, in the case of a rejection, the SCIResponseCode will be set to "RE" and any error codes coming from the system will be shown in the SCIGovtStatusCode element. The customer is responsible for taking action upon receiving an error code and a message from the IRBM system.

Step 1: Supplier sends a POST Request to Sovos

The buyer sends a POST request to the /documents/MY/action endpoint.

To make this request, set the following request body parameters:

Step 2: Sovos transmits Request (to IRBM)

Sovos finds the corresponding document in the system and transmits the cancellation request to IRBM.

Step 3: IRBM processes the Request

IRBM verifies that the 72-hour window has not passed since the original document was issued, and that the document can be cancelled successfully. If the 72-hour window has passed, the taxpayer can still cancel the document by issuing a credit note, debit note, or refund note separately.

Step 4: IRBM returns the Response

IRBM returns the success message, or the error message if the cancellation could not be performed.

Step 5: Taxpayer retrieves the Application Responses

It is highly recommended that clients configure their Application Response attachments as download links instead of base64 encoded data to avoid potential size limitations when retrieving responses. The default option is "download links".

• When using "download links" option, the response contains a URL from where the file can be downloaded.

• When using "binary data" option, the file itself is embedded in the response encoded in base64.

This configuration is available through our Professional Services team.

As a response to the initial sending of the document, the client will receive a JSON response message with an HTTP status code of 202 (asynchronous transaction). This means that the taxpayer must retrieve the application responses that become available during the transaction, which provide status information.

Clients have the option to retrieve application responses (notifications) in one of two ways:

Step 6: Taxpayer marks the Application Responses as Acknowledged

After retrieving application responses, the supplier must process them and mark them as acknowledged. This can be done by sending a PUT request to the /notifications/MY endpoint.

To make this request, set the following request body parameters:

Error Handling

Customers need to adhere to the error handling principles outlined on the responses page.

In general, all error codes in the 400 range are client errors, so the customer needs to analyze them. After fixing the error, it's possible to resend the request. Error codes 408 and 429 are exceptions: in these cases, customers should wait at least 60 seconds before retrying. Error codes in the 500 range indicate server errors. When these occur, customers should resend the request following the guidance provided on the responses page, which also lists all error codes that the Indirect Tax API may return. This government web page contains documentation about the API that includes all the error codes and messages that can be returned, and can be used for error handling.

Errors coming from the IRBM system will be shown in the application response. This means that, in the case of a rejection, the SCIResponseCode will be set to "RE" and any error codes coming from the system will be shown in the SCIGovtStatusCode element. The customer is responsible for taking action upon receiving an error code and a message from the IRBM system.

Step 1: Buyer Sends a Consultation Request for a Specific UUID to Sovos

The customer sends a POST request to the /v1/documents/MY/consultation.

Request body parameters:

Request Sample

curl --location --request POST 'https://api-test-tls.sovos.com/v1/consultations' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "consultationCode": "document.retrieval",
    "productId": "MY_UBLInvoice__1.0",
    "country": "MY",
    "company": {
        "taxId": "<company tax id>"
    },
    "documents": [
    {
        "metadata": {
            "uuid": <UUID of the document>
        }
     }
   ]
}

Response Sample

{
    "message": "OK",
    "status": 200,
    "success": true,
    "data": {
        "completed": true,
        "detailsDto": {
            "completed": "Success",
            "messages": [],
            "documents": [
                {
                    "key": "M32Z3ZDRJVK2W0535KXFK2DJ10_DocumentDetails.json",
                    "data": "eyJ1dWlkIjoiTTMyWjNaRFJKVksyVzA1MzVLWEZLMkRKMTAiLCJzdWJtaXNzaW9uVWlkIjoiNDE2SEZLWDZXUThGRDBZMzVLWEZLMkRKMTAiLCJsb25nSWQiOiJONDZFNjM3ME5RWDJEQ1pFNUtYRksyREoxMFEwcnhhbjE3MzIwMzMxMTUiLCJkYXRlVGltZVJlY2VpdmVkIjoiMjAyNC0xMS0xOVQxNjoxODozNVoiLCJkYXRlVGltZVZhbGlkYXRlZCI6IjIwMjQtMTEtMTlUMTY6MTg6MzZaIiwic3RhdHVzIjoiVmFsaWQiLCJjcmVhdGVkQnlVc2VySWQiOiJDODczNjg2MDMwOmZkNTlmY2NkLTk1OTctNDY0OS1iNmNiLWI4MTc4OGJmNzgyOCIsImRvY3VtZW50U3RhdHVzUmVhc29uIjpudWxsLCJjYW5jZWxEYXRlVGltZSI6bnVsbCwicmVqZWN0UmVxdWVzdERhdGVUaW1lIjpudWxsLCJ2YWxpZGF0aW9uUmVzdWx0cyI6eyJTdGF0dXMiOiJWYWxpZCIsIlZhbGlkYXRpb25TdGVwcyI6W3siU3RhdHVzIjoiVmFsaWQiLCJFcnJvciI6bnVsbCwiTmFtZSI6IlN0ZXAwMy1EdXBsaWNhdGVkIFN1Ym1pc3Npb24gVmFsaWRhdG9yIn0seyJTdGF0dXMiOiJWYWxpZCIsIkVycm9yIjpudWxsLCJOYW1lIjoiU3RlcDA0LUNvZGUgRmllbGQgVmFsaWRhdG9yIn0seyJTdGF0dXMiOiJWYWxpZCIsIkVycm9yIjpudWxsLCJOYW1lIjoiU3RlcDA1LVRheHBheWVyIFByb2ZpbGUgVmFsaWRhdG9yIn0seyJTdGF0dXMiOiJWYWxpZCIsIkVycm9yIjpudWxsLCJOYW1lIjoiU3RlcDA2LURvY3VtZW50IFJlZmVyZW5jZXMgVmFsaWRhdG9yIn0seyJTdGF0dXMiOiJWYWxpZCIsIkVycm9yIjpudWxsLCJOYW1lIjoiU3RlcDA3LURvY3VtZW50IEN1cnJlbmN5IFZhbGlkYXRvciJ9XX0sImludGVybmFsSWQiOiIwMS1CdXllci1yZWplY3Rpb24iLCJkYXRlVGltZUlzc3VlZCI6IjIwMjQtMTEtMTdUMDA6MDA6MDBaIiwidHlwZU5hbWUiOiJJbnZvaWNlIiwidHlwZVZlcnNpb25OYW1lIjoiVmVyc2lvbiAxIiwiaXNzdWVyVGluIjoiQzg3MzY4NjAzMCIsImlzc3Vlck5hbWUiOiJBTVMgU2V0aWEgSmF5YSBTZG4uIEJoZC4iLCJyZWNlaXZlcklkIjoiQzg3MzY4NjAzMCIsInJlY2VpdmVyTmFtZSI6IkhlYmF0IEdyb3VwIiwidG90YWxFeGNsdWRpbmdUYXgiOiIxNDM2LjUiLCJ0b3RhbERpc2NvdW50IjoiMTQzNi41IiwidG90YWxOZXRBbW91bnQiOiIxNDM2LjUiLCJ0b3RhbFBheWFibGVBbW91bnQiOiIxNDM2LjUifQ==",
                    "mimeType": "application/json"
                }
            ]
        }
    }
}

Response Sample with an Error

{
    "timestamp": 1732034087,
    "message": "TaxAuthorityRejectedError",
    "status": 200,
    "success": false,
    "errors": [
        {
            "subCode": "404",
            "message": "It seems that you are not authorized to get document details"
        }
    ]
}

Step 2: Sovos Validates the Request and Calls IRBM

Upon receipt of the request, Sovos validates the request and calls IRBM to retrieve the details for the given UUID.

Step 3: IRBM Returns the Document Details

IRBM returns all the details for the given UUID.

Step 4: Sovos Returns the Document Details

After receiving the details for the given UUID from IRBM, the Sovos Platform builds the consultation response that is returned to the user. This response contains a JSON object representing the details of the document, encoded in base64.

Error Handling

In the event of an error, the response will return a generic 200 status notifying the user that the call was successful, but the content of the response will contain the "errors" object instead.

Outbound Mock

The Outbound Mock simulates sending documents to the Tax Authority. To use the mock service, customers must upload specific credentials using the Configurations v2 resource. Afterward, they can proceed to issue documents.

How to Configure the Outbound Mock

To use the mock service for Malaysia Outbound, configure any arbitrary credentials (inside the value object) via the Settings endpoint from Configurations v2.

Here is a sample request:

curl --location --request POST 'https://api-test.sovos.com/v2/configurations/organizations/YOUR-ORG-ID/settings' \
--header 'x-correlationId: developer-guide' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "context": "transmission",
        "configurations": [
            {
                "name": "partner_credentials_irbm",
                "value": {
                    "client_id": "INSERT-ARBITRARY-CLIENTID-HERE",
                    "client_secret": "INSERT-ARBITRARY-SECRET-HERE"
                },
                "scope": {
                    "category": "MY_INV",
                    "productId": "my_UBLInvoice__1.0",
                    "orgId": "YOUR-ORG-ID",
                    "taxId": "YOUR-COMPANY-TAXID"
                }
            }
        ]
    }
]'

How to Use the Outbound Mock

When sending a document with a POST request to the Send a new Document endpoint to reach the mocked services, the x-correlationId value must end with "-mock". For example, x-correlationId = "123-mock". Sovos' solution distinguishes between the mocked Outbound service and the real Tax Authority UAT environment based on the presence of this value.

When using the GET method with the Notifications endpoints, the x-correlationId doesn't need to end with "-mock". This is because the Sovos solution does not differentiate between mocked notifications and notifications related to the real Tax Authority UAT environment — they are both treated as "notifications", which can be retrieved normally. The same reasoning applies to using the PUT method with the Mark Notifications as acknowledged endpoint: there's no need to add an x-correlationId ending with "-mock".

To test Outbound against the real Tax Authority UAT environment, it is crucial to follow the correct prerequisites and configuration steps. This involves obtaining the real Tax Authority credentials and configuring them in the Sovos solution. So, when issuing the document, ensure that the x-correlationId doesn't end with "-mock".

Outbound Mock Validation

The main purpose of the mocked service is to allow customers in the early stages of integration to test the end-to-end flow without being blocked by the lack of real Tax Authority credentials. Only a limited set of scenarios can be tested based on the document's content, as explained in the list below:

• If one or more required fields in the document are missing or empty.

• Submit exactly same document (same hash) within 10 minutes.

  Request payload is identical to a previous payload sent in the last 10 minutes. Try to submit payload after {secondsRemaining} seconds (seconds remaining replaced with actual value).

• If the request hash value of the document is not the same as the hash we compute based on the document.

  Document hash is not valid.

• IssueDate or IssueTime missing in the document.

  IssueDate OR IssueTime is missing in the document.

• IssueDate or IssueTime are not valid date times.

  IssueDate OR IssueTime is not in a valid format.

• IssueDateTime (which is created combining IssueDate and IssueTime from document) is over 72 hours in the past.

  Issuance date time value of the document is too old that cannot be submitted.

• If IssueDateTime is in the future.

  Document issuance date time is in the future.

• UUID is not found.

  Document UUID :uuid is not found. Please ensure the UUID is correct.