Company account management

You can use either the SOAP API, REST API or the user interface to open and manage company accounts. However, the user interface requires manual work so if the integration will have multiple companies or a complex set-up, API is recommended.

How to open company accounts

Steps to open account over API

  1. Create a company account with basic settings
  2. Configure settings for the account
  3. Verify the account either with
    1. Visma Sign - end customer signs electronically to authorise account (default)
    2. Partner authentication - account authorised based on customer authentication earlier on partner side

1. Create company account

When company account has been created, it can be configured by updating company settings, adding new users and activating services.

SOAP

  • register_with_password
    The method registers a new company account with default settings and adds/creates a user based on the email in the user_email parameter

Note how the user creation works!

  • If user given in the user_email parameter doesn’t exist, a new user is created based on email and added to the company
  • If user given in the user_email parameter exists, this existing user is added to company

In situations where a new user is created, method returns unique company_uuid and user_api_key. If method is called with an existing user, for security reasons only company_uuid is returned.

REST (Experimental)

Creating a company requires a vendor key and a user API key. You may use an existing user or create a new one.

2. Configure basic account settings

When company account has been created, it can be configured by updating company settings, adding new users and activating services. Some services for receiving can only be activated after the verification step.

SOAP

API methods:

You can update the receiving setting (enable/disable) also using company_invoice_receiving. Note, that invoice receiving needs to be enabled in order to register company account to Peppol network or to use additional services such as Scanning.

REST

Services allowed for an unverified company, for basic settings

Other services can be activated after the authorization is completed.

3. Verify account / Know Your Customer process

Verifying the account means that someone strongly authenticated needs to verify the account for the company before it can be used for sending and downloading. The purpose is to ensure customer is known and to prevent potential misuse of service. For Finnish companies, verification creates also automatically the request to open bank network.

Authorisation options

The authentication of customer can happen as part of the partner onboarding process or with Visma Sign electronic signature service. Visma Sign is always used if the account is registered over Maventa UI. To use the account it is also required that the customer has accepted the Terms of Service .

Before implementing the verification part, decide which authorisation method suits your integration. If you want to use the partner authorisation, you need to check with Maventa that your process to authenticate the customer meets the authorisation requirements.

Visma Sign authorisation

The account verification takes place with Visma Sign electronic signature service. A person who has rights to represent company related to electronic invoicing authenticates strongly with bank credentials, BankID or mobileID and signs a document where they confirm that account can be taken into use for the company.

Partner authorisation

If the customer has already signed the Terms of Service and has been strongly authenticated on the partner side before they start to use Maventa, it is possible to agree with Maventa about verification without the Visma Sign step. In this case, the authorisation of the account is not a visible step to the end customer when they open Maventa account. The partner provides in the authorisation API call an identifier that can be stored and used to link to authorisation event on their side (e.g.contract number, signing eventID). If needed partner has to be able to show that the authorisation has happened.

REST (Experimental)

SOAP

  • Verification happens by calling authorize_companies API method after account has been created.
  • Same API method is used regardless of authorisation method (Maventa sets partner’s vendor_api_key so that the correct authorisation option, Visma Sign or partner, follows the call).
  • When the verification happens account status (company_state parameter) changes from unverified (-1) to verified (1) and the account is ready to be used.

API methods

  • authorize_companies
    Method to verify company accounts.
  • company_auth_status
    Method to see the company authorisation status
    • In order to start sending and receiving invoices the company_state needs to be verified (1).

Verification statuses

Company_state Description
verified (1) Company is authorised. Account can be used to send, download and register to Peppol network.
unverified (-1) Authorisation required. Sending, downloading and registering to Peppol network is not possible.
unknown (0) Authorisation functionality not in use. Account has not been verified with authorize_companies method, but can be used to send, download and register to Peppol network. This status is possible for older accounts / integrations.
Example - Visma Sign verification with SOAP

Starting point:

  • Account has been created - authorisation status is (-1) = unverified
  • Authorize_companies API method is called to start Visma Sign flow
Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:sec="https://secure.maventa.com/">
  <soapenv:Header/>
  <soapenv:Body>
    <sec:authorize_companies soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <api_keys xsi:type="sec:ApiKeys">
        <user_api_key xsi:type="xsd:string">accesstoallcompaniestobeverified</user_api_key>
        <vendor_api_key xsi:type="xsd:string">vendorkey</vendor_api_key>
        <company_uuid xsi:type="xsd:string">acompanyuserhasaccessto</company_uuid>
      </api_keys>
      <auth_email xsi:type="xsd:string">emailofsigner@signer.com</auth_email>
      <company_ids xsi:type="sec:StringArray" soapenc:arrayType="xsd:string[1]">
        <xsd:string>513202b6-a681-4061-bfc0-23e4983fc070</xsd:string>
      </company_ids>
      <locale xsi:type="xsd:string">FI/SE/NO/EN/DK</locale>
      <options xsi:type="xsd:string"></options>
    </sec:authorize_companies>
  </soapenv:Body>
</soapenv:Envelope>

After Visma Sign flow has been completed, account is set to verified state (1) and is ready to be used.

Note!

  • The signee/authoriser should be person who has rights to represent company in matters conserning electronic invoicing/ordering
  • You can use parameter locale to select the language for the PDF document.
  • The invitation to sign is valid for 7 days. If signing is not done in this time, new request needs to be sent.
  • In production, company authorisation status is updated from Visma Sign every 15 minutes.
  • In testing, there are no automatic updates but you need to call company_auth_status to get the status updated.
Visma Sign test credentials

You can complete Visma Sign authorization request with these test credentials:

  • user ID: testtest@test.test
  • password: xO70MVYD0CXaKcQ2

For bankID you can use Nets test users from https://www.nets.eu/developer/e-ident/eids/Pages/testusers.aspx

Process overview Company account activation

Example - partner verification

In Partner verification, verifying the account is not a visible step to end customer company.

  • Starting point: Account has been created - authorisation status is (-1) = unverified

Authorize_companies method called - link to authentication event on the partner side given in the call in options - parameter.

Example API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:sec="https://secure.maventa.com/">
  <soapenv:Header/>
  <soapenv:Body>
    <sec:authorize_companies soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <api_keys xsi:type="sec:ApiKeys">
        <user_api_key xsi:type="xsd:string">accesstoallcompaniestobeverified</user_api_key>
        <vendor_api_key xsi:type="xsd:string">vendorkey</vendor_api_key>
        <company_uuid xsi:type="xsd:string">acompanyuserhasaccessto</company_uuid>
      </api_keys>
      <auth_email xsi:type="xsd:string"></auth_email>
      <company_ids xsi:type="sec:StringArray" soapenc:arrayType="xsd:string[1]">
        <xsd:string>company_uuid_to_be_verified</xsd:string>
      </company_ids>
      <locale xsi:type="xsd:string">FI/SE/NO/EN/DK</locale>
      <options xsi:type="xsd:string">{"authorization_method":how+identifierlinkingtoauthevent"}</options>
    </sec:authorize_companies>
  </soapenv:Body>
</soapenv:Envelope>

After the API call, account is set to verified state (1) and is ready to be used.

Authorisation for mass registrations

In cases where the same signee has rights to represent more than one company it is possible to use one signing for multiple companies at the same time. For example in case of a housing company or accounting office that has signing / representation rights for multiple customers. One API call can be used to authorize up to 50 companies in time. For the authorisation to work, the companies that are authorised need to be from the same country.

Company accounts over UI

New companies with a new user can be created for:

If you need to create a new company for an existing user, log-in to Maventa UI first.

Before production account can be used it needs to be verified using strong authentication and electronic signing. When the user logs in to the account for the first time, user needs to go through a set-up wizard where they add information of the company and configure some of the basic settings. The last step of the wizard is the company verification process with Visma Sign service. This signing process is the same as described with Visma Sign for API above, but in this case the process is initiated from UI. Visma Sign authorisation is not required if the company is created in the testing environment.

Note

  • The language of the PDF document is defined based on company country
  • the language of the Visma Sign invitation email is defined based on the language that is set for the user interface at the time the authorisation request is sent. E.g. when UI is in Finnish, Visma Sign email is sent in Finnish.

Different settings can be configured further in the web UI after user has logged in. Dedicated sections help to find the wanted settings and tell more information what the settings are about.

Partner accounts

In Maventa there are two type of accounts; Company accounts and Partner accounts. Company account is the default account type. Partner accounts are used by the integrating partners (ERPs and such with multiple customers).

The key difference between a Partner and a regular Company account is that Partner accounts have an own identifier, vendor_api_key, that is used to link actions to the partner company. The vendor api key is used for billing and reporting purposes. One Partner company can own many vendor_api_keys, for example one for each country they have customers in.

Integrators don’t need to worry about controlling the account types, all accounts registered to Maventa are first created as Company account and changed to account type Partner if and when needed by Maventa.


API endpoints tagged with [EXPERIMENTAL] should be considered as work in progress making them subject to change. Once the tag is removed, the contracts for these endpoints should be considered stable.