Dear Lex,
Thank you for reaching out. Please find our response below:
1. Taxpayer Login
- What is the use case for tax payer login? Taxpayer login allows an APP to retrieve the entity ID linked to a taxpayer, which serves as a unique key for accessing the taxpayer’s e-Invoicing configuration and profile.
- Is the expectation that APP are expected to authenticate Tax Payer before allowing them to access the Invoice APIs? The e-Invoice APIs are publicly accessible. However, to onboard a taxpayer and retrieve their e-Invoicing profile, the APP must either use the taxpayer's authentication (Taxpayer Auth) or invoke the GET /entity endpoint, and this is only possible if the taxpayer has already enabled its entity for e-Invoicing.
- Is there a test taxpayer login email and password that can be used for test? No. Test sign-in credentials are not provided
.
2. Get Entity by Business ID
- Am I able to get the Entity details of any taxpayer or only those where I am their APP? No. You can only retrieve entity details for taxpayers who have explicitly selected you as their APP.
- What is an Entity, how is it different from taxpayer and Businesses? It looks like an Entity can have multiple businesses? An Entity represents the taxpayer’s identity in the e-Invoicing system. It is uniquely tied to the TIN. In this context, each taxpayer equals one entity; an entity cannot have multiple businesses.
3. Invoice Signing/Submission by Taxpayer
- Is it fair to say the purpose of signing an invoice is to register the Invoice with FIRS? Yes. Digital signing serves as the taxpayer’s official submission of the invoice to FIRS, registering it for fiscalization and compliance.
4. Invoice Validation Use Cases
- What is the use case for validating a full invoice document (POST /api/v1/invoice/validate) vs validating by IRN (POST /api/v1/invoice/irn/validate)? Both endpoints are used by the sender. While POST /invoice/validate validates the full invoice structure and content, POST /invoice/irn/validate is specifically used to verify the integrity of the IRN computation. It's advisable to validate the IRN during implementation to prevent mismatches during full invoice validation.
- Is the expectation that full document invoice validation is for the sender, while validation by IRN is for Receiver? Both validation endpoints are intended for the sender to ensure accuracy prior to Signing.
5. Invoice Confirmation (GET /api/v1/invoice/confirm/{IRN})
- What is the exact purpose of this endpoint, is it equivalent to retrieving the invoice status, or does it serve a different purpose? This endpoint returns the current processing status of a specific invoice, confirming whether it has been transmitted or acknowledged.
6. TIN Lookup (GET /api/v1/invoice/transmit/lookup/tin/{TIN})
- What is the intended purpose of this endpoint? This endpoint retrieves the taxpayer’s invoice exchange details, including their accounting party profile and corresponding APP.
- Is it meant to validate a buyer/supplier TIN before transmission? Primarily, it is used to determine the party’s metadata and APP affiliation for routing purposes, not to validate tax registration.
- When is validation by IRN used vs TIN validation? IRN validation is used during invoice creation to verify the integrity of the computed IRN while TIN lookup is used before invoice transmission to resolve the buyer’s routing and APP details.
7. Updating Invoice status to PAID, REEJCTED etc
- Who can/should update invoice status, it is the sender of the invoice or the receiver? The sender is responsible for updating the invoice status, as the sender holds legal liability for the transaction.
- Does MBS have validation on this? Currently, validation is limited, but the system roadmap includes policy enhancements to tie every financial transaction to an IRN for validation and traceability.
8. Testing the Full Lifecycle
- What is the recommended way to test the full invoice lifecycle, especially how to confirm receipt of transmitted Invoice as a receiver - I have not figured a way to be a sender and a receiver at the same time. The same for pulling of transmitted invoices. Currently, we are unable to fully test some steps such as confirm receipt, and pull because its not clear how to register as a receiver linked to me as an APP? To perform end-to-end (E2E) testing, configure your test business as both the Accounting Supplier and Customer. With a properly configured webhook, this allows you to simulate invoice issuance, receipt, confirmation, and pull in a closed test loop.
9. Confirming Transmitted Invoices (PATCH /api/v1/invoice/transmit/{IRN})
- Is there any compliance or regulatory requirement that this confirmation must come from the receiver (taxpayer) or can the APP confirm on behalf of the taxpayer? Will this be left to the discretion of the APP? The receiving APP is responsible for confirming receipt on behalf of the taxpayer, as part of the invoice exchange protocol.
10. Invoice Pulling vs Search vs Download
- What is the functional difference between: Pull is for transmission logs; Download is for receiving payload delivery.
GET /api/v1/invoice/transmit/pull - Used by the APP to retrieve all invoices transmitted by the APP to various recipients.
GET /api/v1/invoice/download/{{IRN}} - Used by the receiving APP to download a specific invoice transmitted to its subscribed taxpayer.
- Are there specific use cases for each that we should be aware of? Is the pull used by receiver to fetch all invoices that are meant for taxpayers subscribed to the APP? It can be used by both the the Receiver and Sender APP
- The documentation does not have sample response for all the transmit API calls, pls can we get sample response json for them? FIRS will update the official API documentation to include sample JSON responses for all Transmit API calls.
11. Invoice Status Update
- Is it correct to assume that only the invoice receiver should be able to:
- Update invoice status (PATCH /api/v1/invoice/update/{IRN})? Incorrect. Only the sender has permission to update invoice status (e.g., PAID, REJECTED).
- Confirm transmitted invoice (PATCH /api/v1/invoice/transmit/{IRN})? The receiver’s APP confirms receipt of the invoice.
- Does the MBS system enforce this rule (e.g. by checking business identity), or is this the responsibility of the APP? Yes. The MBS platform validates all the details to ensure conformity before validating a transaction.
- Can a sender update the invoice status, or is that strictly limited to the receiver? Yes. Status updates are strictly the sender’s responsibility and must align with the invoice lifecycle logic.
- Are there any compliance or regulatory requirement around who access an invoice e.g. only parties (sender/receiver) can access an Invoice and if so does MBS do any valdiation or APP are expected to do that? No. Only parties directly involved in the transaction (sender or receiver) are permitted to access, lookup, or download an invoice. MBS enforces this through identity validation and access control.
