Invoice Receiving
Maventa makes it easy to receive invoices from multiple sources including country-specific e-invoicing networks, Peppol, and PDF scanning services. Once activated, Maventa registers your company in the relevant electronic address directories and assigns you an electronic invoice address (EIA) that senders can use to deliver invoices directly to you. <
All invoices first arrive in your Maventa account, where they can be downloaded or fetched via API into your system. You can also use webhooks to create a smooth, automated receiving flow and integrate the Detect service for validation and fraud detection. For extra protection, the fraud reporting feature allows you to flag suspicious senders and help prevent invoice fraud across the network.
To start receiving invoices, make sure you have:
- Company account enabled for receiving: Your company must have an active Maventa account with invoice receiving enabled.
- Invoice XML handling capabilities: In the download process you can select in which XML format you want to download the invoice into your system. Maventa supports a variety of international and national formats. See the full list of supported formats and more information about invoicing formats.
To start receiving invoices, the company needs to enable the invoice receiving setting in Maventa, also referred to as the VISMA Network. This setting acts as the main control for receiving e-invoices, allowing the company to receive invoices internally from other Maventa users, and depending on the country also from other operators or banks.
Once this main control is turned on, additional networks such as Peppol or scanning can be enabled. Enabling these networks means the company will also be registered to receive invoices through those specific channels. We recommend enabling Peppol for all customers to ensure the widest possible reach for receiving invoices.
After activation, the company is automatically registered, depending on the country, in the relevant electronic address directories and assigned an electronic invoice address (EIA) that senders can use to deliver invoices directly. The company also becomes visible as an invoice recipient in Maventa Finder and via our lookup method.
You can check which address registries are used in each country, as well as whether the country supports operator or bank networks, in the country-specific guides. Typically, receiving is activated at the same time the account is registered, but it can also be enabled later if needed.
Call the POST /v1/company/profiles endpoint authenticated with company scope, providing the network VISMA and profiles INVOICE_AND_CREDIT_NOTE:
{
"profiles": [
"INVOICE_AND_CREDIT_NOTE"
],
"network": "VISMA"
}No other parameters are needed. Expect a response of pending. To confirm successful registration, call the GET /v1/company/profiles API method and check that the status has changed to active.
When activating the electronic receiving setting, we recommend that all customers are also registered to receive electronic invoices in the international Peppol network. When company is registered their information is added to Peppol Directory.
Authenticate with company scope and call POST /v1/company/profiles, specifying the network as PEPPOL and profiles INVOICE_AND_CREDIT_NOTE:
{
"profiles": [
"INVOICE_AND_CREDIT_NOTE"
],
"network": "PEPPOL"
}The profile INVOICE_AND_CREDIT_NOTE registers the up-to-date Peppol profiles relevant to the company’s country. The profile covers the below document types:
- Peppol BIS Billing 3.0 Invoice
- Peppol BIS Billing 3.0 Credit Note
Maventa automatically keeps the Peppol registration updated as new invoice profiles are introduced. No need to register new profiles when the format updates, especially for PEPPOLBIS3.
Call GET /v1/company/profiles again to verify that the status of the PEPPOL network registration is active. If you receive the response PROFILE_ALREADY_REGISTERED, it means the company is already registered with another Peppol access point. In this case, the company must first be deregistered by the current access point before Maventa can register it to Peppol.
With registration, the company is visible with an electronic invoicing address (EIA) to suppliers in the Peppol network.
For human users, the Peppol Directory is available as a reference tool. Maventa automatically updates this directory, making your company visible there. Please note that the Peppol Directory is not part of the actual delivery infrastructure, it serves informational purposes only.
To enable receiving of invoice extensions you need to use the following endpoint: PUT /v1/company/profiles/{id}/extensions
Example request:
{
"profile_name": "INVOICE_AND_CREDIT_NOTE",
"extensions": ["GACCOUNT10"]
}Currently only GACCOUNT10 extension for Netherlands is supported.
To view the extensions you need to use the following endpoint GET /v1/company/profiles/{id}.
{
// ...
"profiles_with_extensions": [
{
"profile_name": "INVOICE_AND_CREDIT_NOTE",
"extensions": ["GACCOUNT10"]
}
]
}To disable receiving of invoice extensions you need to use the following endpoint. PUT /v1/company/profiles/{id}/extensions
{
"profile_name": "INVOICE_AND_CREDIT_NOTE",
"extensions": []
}
To determine when an invoice has been received to a company account, you can either listen for webhook notifications or poll the API for incoming invoices. Webhooks are the preferred method, as they provide faster and more efficient delivery compared to regular polling.
With webhooks you can get information right away when a new invoice has arrived and can build a user friendly receiving flow. As a backup routine, we recommend to poll for invoices once a day.
Use the following API to register for invoice receipt events: POST /v1/company/notifications. Example registering for RECEIVED events for invoices:
{
"destination_type": "WEBHOOK",
"destination": "https://your.example/endpoint",
"events": [
"DOCUMENTS.INVOICE.RECEIVED"
]
}{
"id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
"destination_type": "WEBHOOK",
"destination": "https://your.example/endpoint",
"events": [
"DOCUMENTS.INVOICE.RECEIVED"
]
}Maventa will call the specified endpoint with an example payload like this:
{
"event": "DOCUMENTS.INVOICE.RECEIVED",
"company_id": "53a4e05d-42f0-4e76-acd6-968ab4558c6f",
"event_timestamp": "2024-11-23T12:03:48+02:00",
"event_data": {
"invoice_id": "c154feee-399b-488e-aecd-580578b140e0",
"invoice_number": "1002",
"origin": "PEPPOL",
"sender_name": "Sender",
"sender_bid": "937729111"
}
}Example registering for RECEIVED events for invoices with vendor webhooks:
{
"destination_type": "VENDOR_WEBHOOK",
"destination": "https://your.example/endpoint",
"vendor_key": "your_vendor_api_key_here",
"events": [
"DOCUMENTS.INVOICE.RECEIVED"
]
}{
"id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
"destination_type": "VENDOR_WEBHOOK",
"destination": "https://your.example/endpoint",
"events": [
"DOCUMENTS.INVOICE.RECEIVED"
]
}Store the event_data.invoice_id for later processing and deduplication. Refer to the Webhooks guide for more details.
The receiving process works simply by listing new invoices arrived to Maventa and then downloading the invoice and the attachments. If you do not implement the webhooks we do not recommend to make the polling too frequent - usually a couple of times per day is enough
Use GET /v1/invoices with params direction=RECEIVED, received_at_start, and received_at_end to get a list of invoices to download. Method is called per company, so it is only possible to list invoices from one company at a time.
NOTE!
- Call method starting with latest fetch timestamp and ending with current timestamp
- If the API returns error or something unexpected, do not update timestamp but allow retry of listing at a later time
- When the API returns a list of invoices, save invoice IDs locally with a status ‘pending download’ or such
- Timestamp on the server is GMT +2 and differences between client side and server side clocks might create intervals not covered when listing. Therefore, it is recommended that the timestamps have some buffer, for example 1 minute before and after to avoid any gaps in the time
After you have saved the new incoming invoice IDs, download the invoice files and attachments into your system.
Invoice downloading involves obtaining:
- Invoice metadata
- Invoice data
- Invoice attachments
Use GET /v1/invoices/{id} to download the invoice XML file in the specified format, or to download the invoice image.
NOTE!
- Use the local ID list to download an invoice, marking it as successfully retrieved only after it has actually been retrieved (e.g. in case of errors, alert/retry download).
- Since the IDs of the invoices are listed locally, that list can be used to make sure the same invoice is not downloaded twice
To download invoice image you need to use param return_format:
-
ORIGINAL_OR_GENERATED_IMAGE(returns original if one exists, and if not then we generate an image for you) -
ORIGINAL_IMAGE(returns an image only if original exists) -
GENERATED_IMAGE(returns image we generate)
Invoice’s original format is Peppol BIS3 and you download it as Peppol BIS3. You only need the XML file as it has all original attachments embedded to it. In conversion we do not forcefully embed separate attachments.
Invoices’s original format is TEAPPSXML 3.0 and there is also invoice image and extra attachment.
- You download the invoice as Finvoice 3.0 with GET /v1/invoices/{id} by giving
return_formatasFINVOICE30. - Then you can download the possible invoice image or other attachments with same endpoint but
return_formatbeing one of the described above.
Invoices may also contain attachments, listed in the files array of the invoice metadata. Download each attachment separately using GET /v1/invoices/{id}/files/{file_id} with the id from each file entry.
Most often, attachments include an invoice image. It is usually a PDF document with a visual representation of the invoice data. If one is not provided by the sender, Maventa generates it.
In the invoice details origin shows if the received invoice is electronic invoice or scanned invoice. If the invoice origin is SCAN, extra information is provided as origin_type. It informs the type of the scanned invoice eg. if the scanned invoice is received via automatic scanning (AutoScan) or via standard scanning:
-
SCAN_PDF- Scanned from a PDF file -
SCAN_PAPER- Scanned from a paper invoice -
AUTOSCAN- Automatically scanned from a PDF file -
SCAN- Scanned from non-invoice material
Fetch the check results from Maventa.
Use GET /v1/invoices/{id}/detect_results to download the check results based on invoice id.
More information about Detect service.