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.

Typical receiving flow

The following steps describe the recommended flow for receiving invoices:

1. Activate — Enable VISMA Network and Peppol receiving for the company.
2. Listen — Register a webhook for DOCUMENTS.INVOICE.RECEIVED events.
3. Download — When a webhook fires, fetch the invoice XML, image, and attachments by ID.
4. Validate — If Detect is enabled, fetch fraud and validation check results.
5. Back up — Poll GET /v1/invoices once a day to catch any invoices missed by webhooks.

Prerequisites

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: During download, you select which XML format to use. Maventa supports a variety of international and national formats. See the full list of supported formats and more information about invoicing formats.

Step 1: Activate invoice receiving

To start receiving invoices, enable the VISMA Network setting. This is the main control for receiving e-invoices in Maventa. It allows the company to receive invoices from other Maventa users and, depending on the country, also from other operators or banks.

Once VISMA Network is turned on, additional networks such as Peppol or scanning can be enabled separately. Maventa recommends enabling Peppol for all customers to ensure the widest possible reach for receiving invoices.

After activation, the company is automatically registered in the relevant electronic address directories (depending on the country) 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 the 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.

Activate VISMA Network

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 the status field in the response to be pending. To confirm successful registration, call the GET /v1​/company​/profiles endpoint and check that the status has changed to active.

Register company as Peppol receiver

When activating the electronic receiving setting, Maventa recommends that all customers are also registered to receive electronic invoices in the international Peppol network. When a company is registered, its information is added to the 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 automatically registers both document types for Peppol BIS Billing 3.0. Some countries also include additional, country-specific profiles automatically. Maventa automatically keeps the Peppol registration updated as new invoice profiles are introduced. There is no need to register new profiles when the format updates.

Call GET /v1​/company​/profiles again to verify that the status of the PEPPOL network registration is active. If the response contains the error code PROFILE_ALREADY_REGISTERED, the company is already registered with another Peppol access point. The current access point must deregister the company before Maventa can complete the registration.

With registration, the company is visible with an electronic invoicing address (EIA) to suppliers in the Peppol network.

The Peppol Directory is available as a reference tool for looking up registered companies. Maventa automatically updates this directory, making your company visible there. Note that the Peppol Directory is not part of the actual delivery infrastructure — it serves informational purposes only.

Deactivate invoice receiving

To stop receiving invoices on a specific network, delete the corresponding network registration. This removes the company from the associated electronic address directories, and senders can no longer deliver invoices to the company through that network.

First, retrieve the profile ID by calling GET /v1​/company​/profiles with company scope. Filter by network if needed — for example, ?network=VISMA or ?network=PEPPOL. The response includes the id for each active registration.

Then, call DELETE /v1​/company​/profiles/{id} with the profile id to delete the registration.

To deregister from Peppol specifically, use the same approach: find the Peppol profile ID from the list and delete it. The company is then removed from the Peppol network and the Peppol Directory. Senders looking up the company through Peppol will no longer find a registered e-invoicing address.

Each network registration can be deactivated independently. For example, deleting the Peppol registration does not affect the VISMA Network registration, and vice versa.

Receiving invoice extensions

To enable receiving of invoice extensions, call PUT /v1/company/profiles/{id}/extensions.

Example request:

{
  "profile_name": "INVOICE_AND_CREDIT_NOTE",
  "extensions": ["GACCOUNT10"]
}

Currently, Maventa supports only the GACCOUNT10 extension for the Netherlands.

To view the active extensions, call GET /v1/company/profiles/{id}.

{
  // ...
  "profiles_with_extensions": [
    {
      "profile_name": "INVOICE_AND_CREDIT_NOTE",
      "extensions": ["GACCOUNT10"]
    }
  ]
}

To disable receiving of invoice extensions, call PUT /v1/company/profiles/{id}/extensions with an empty extensions array:

{
  "profile_name": "INVOICE_AND_CREDIT_NOTE",
  "extensions": []
}

Step 2: Fetch received invoices

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.

Webhooks

Webhooks notify your system immediately when a new invoice arrives, enabling a seamless automated receiving flow. As a backup routine, Maventa recommends polling for invoices once a day.

Register for webhook notifications for received invoices

Register for invoice receipt events by calling 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 calls the specified endpoint with a 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. Maventa may deliver the same webhook event more than once (for example, if your endpoint is temporarily unreachable), so always check whether an invoice ID has already been processed before downloading it again.

Your endpoint should return an HTTP 200 status code to acknowledge receipt. If Maventa does not receive a 200 response, the webhook is retried. Refer to the Webhooks guide for full details on retry behaviour, payload signatures, and configuration.

Polling

If you do not use webhooks, you can poll the API to list new invoices and then download them with their attachments. Maventa recommends polling no more than once or twice per day. Even when using webhooks, poll once a day as a backup to catch any missed deliveries.

List new received invoices

Use GET /v1/invoices with parameters direction=RECEIVED, received_at_start, and received_at_end to get a list of invoices to download. This method is called per company, so it is only possible to list invoices from one company at a time.

The timestamp parameters use ISO 8601 format, for example:

GET /v1/invoices?direction=RECEIVED&received_at_start=2025-01-15T08:00:00%2B02:00&received_at_end=2025-01-15T20:00:00%2B02:00

The response is paginated. Use the page and per_page parameters to iterate through results. Check the response headers or result count to determine whether more pages are available.

Download invoice based on ID

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. Set the return_format parameter to the desired format.

Common return_format values for XML download:

For the full list of supported formats, see the Validator API specification and the invoicing formats page.

Download invoice image and attachments

To download the invoice image, use the return_format parameter:

• ORIGINAL_OR_GENERATED_IMAGE — returns the original image if one exists, otherwise Maventa generates one
• ORIGINAL_IMAGE — returns an image only if the original exists
• GENERATED_IMAGE — returns an image generated by Maventa

Example: Original format Peppol BIS3

If the 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.

Example: Original format TEAPPSXML 3.0 downloaded as Finvoice 3.0

If the invoice’s original format is TEAPPSXML 3.0 and it includes an invoice image and extra attachments:

• Download the invoice as Finvoice 3.0 with GET /v1/invoices/{id} by setting return_format to FINVOICE30.
• Then download the invoice image or other attachments using the same endpoint with return_format set to one of the image options 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 — a PDF document with a visual representation of the invoice data. If one is not provided by the sender, Maventa generates it.

Invoice origin and origin_type details

In the invoice details, the origin field indicates the source of the received invoice — for example, PEPPOL, VISMA, or SCAN. If the origin is SCAN, the origin_type field provides additional detail about the scanning method:

Error handling

When building your receiving integration, plan for common failure scenarios:

Step 3: Fetch Detect results

If the Detect service is enabled for the company, fetch the validation and fraud check results for each received invoice.

Use GET /v1/invoices/{id}/detect_results to download the check results based on invoice ID.

The response includes results from checks such as VAT register verification, bank account change detection, and warning list cross-referencing. Use these results to flag invoices that require manual review before approval.

For more information, see the Detect service documentation and Fraud reporting.