CS

PaymentService web guide

Home / Documentation / Manuals /

PaymentService web guide

CS

1. General information

PaymentService is a service that runs in the background of the Windows operating system and automatically creates bank payments, marks invoices and other obligations as paid based on communication with the bank. It is installed as an add-on to the NET Genium ERP application and requires a technology mailbox to which email messages about incoming and outgoing payments are sent by the bank. It automatically creates bank payments from e-mail messages delivered to the technology box and assigns them to specific invoices or other obligations.

  • The basic condition is that the bank must support sending e-mail messages about incoming and outgoing payments.
  • Payments are automatically matched with the relevant documents in NET Genium based on the variable symbol and the amount; for received invoices and other payables, the accounts from which and to which the payment was sent are compared as well when the bank e-mail states them. A payment is matched only when exactly one document corresponds to it, and with an invoice only when it carries a variable symbol.
  • Paired documents are automatically marked as partially or fully paid. An invoice is paid partially only when matching of partial payments is allowed in the ERP (the default); otherwise the payment amount must equal the amount remaining to be paid. Other receivables and payables are matched only with a payment of the full document amount including VAT.
  • The service works for both incoming and outgoing payments.

When a payment is recorded, a record of this payment is automatically created in the “Bank” application in the “Bank payments” table. If the payment is matched with a document, this document is also automatically updated; after a match with an issued invoice or an issued advance invoice, information about the payment is also sent by e-mail (see chapter 10).

2. Supported banks

  • Raiffeisenbank
  • Komerční banka
  • FIO
  • Česká spořitelna – only outgoing payments (payment of received invoices and other obligations) and in addition, sending an email must be set for each outgoing payment
  • UniCredit bank

PaymentService recognizes the bank e-mail by the address of its sender, so the e-mail must arrive in the technology mailbox directly from the bank's address; a forwarded e-mail is not processed. The supported currencies are CZK, EUR and USD, for FIO only CZK.

3. Required files

For the PaymentService to work, it is necessary to have the following files in its directory:

  • PaymentService.exe
  • ERP.dll
  • ngef.dll
  • NETGeniumConnection.dll

+ configuration XML file for each technology box.

4. Technology box

A necessary condition for the PaymentService is the existence of a technological mailbox to which e-mail messages about incoming and outgoing payments are sent by the bank. The usual name is, for example, “ps@firma.cz” or “ps” in front of the culprit and with the domain of the given company.

The actual sending of e-mail messages about incoming and outgoing payments must be done manually in the application supplied by the banking service provider, typically in Internet banking.

PaymentService recognizes bank e-mails by the sender address stated in the message. It is therefore advisable to secure the technology mailbox so that it accepts only mail that the mail server verifies as sent by the bank (for example by SPF, DKIM and DMARC checks or by a rule that rejects other mail), and not to publish its address.

5. Configure Azure Active Directory

PaymentService requires additional manual configuration of Azure Active Directory, i.e. Microsoft Entra ID, in cases where it downloads emails from a technical mailbox operated using Microsoft cloud services.

5.1. Configuration on the “https://portal.azure.com” portal

  • NET Genium configuration on “https://portal.azure.com” portal:
    • App Registration “NET Genium” on webside [[https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps]
      • portal.azure.com / App registrations
      • NET Genium as the application name
      • Retrieve the Application (client) ID, which is automatically created during application registration
  • Application (client) ID
    • Retrieve the Directory (tenant) ID, which is automatically created during application registration
  • Directory (tenant) ID
    • Create client secret code
  • portal.azure.com / App registrations / NET Genium / Certificates & secrets / New client secret
    • Setting API permissions for Microsoft Graph
  • portal.azure.com / App registrations / NET Genium / API permissions / Add a permission / Microsoft Graph
  • API permission “Microsoft Graph – Mail.ReadWrite”, type “Application”
  • API permission “Microsoft Graph – User.Read.All”, type “Application”
  • If the service downloads e-mails via POP3 with OAuth2 authentication (the “pop3OAuth” key), the permission “Office 365 Exchange Online – POP.AccessAsApp”, type “Application”, is needed as well; the application must also be registered in Exchange Online and have access to the technology mailbox.
  • The service does not need the permissions “Microsoft Graph – Calendars.ReadWrite” and “Microsoft Graph – Group.ReadWrite.All”; they are needed only when the application registration (the “MicrosoftOAuth.json” file) is shared with CRMService or with the ERP integration with OneDrive and Microsoft Teams.

5.2. NET Genium configuration

  • Create the configuration file “NETGenium\Config\MicrosoftOAuth.json”
    • Set file content to: “{"web":{"client_id":"Application ID (client)","tenant_id":"Directory ID (tenant)","auth_uri":"https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize","token_uri":"https://login.microsoftonline.com/organizations/oauth2/v2.0/token","client_secret":"client secret code"}}”

5.3. Troubleshooting or resolving issues with email retrieval

5.3.1. General

  • PaymentService stores the email-retrieval process, including any errors, in the log file “Logs\{yyyy-MM-dd}.log”
  • A detailed log of communication with Microsoft services is stored in “Logs\Office365-{yyyy-MM}.log”

5.3.2. Invalid client secret provided...

  • The server returns the error: Invalid client secret provided. Ensure the secret being sent in the request is the client secret value, not the client secret ID
  • Verify that the “client_secret” value in “MicrosoftOAuth.json” is correct

5.3.3. Application with identifier 'xxxxxxxxxx' was not found...

  • The server returns the error: Application with identifier 'xxxxxxxxxx' was not found in the directory 'firma s.r.o'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant.
  • Verify that the “tenant_id” value in “MicrosoftOAuth.json” is correct

5.3.4. Access is denied. Check credentials and try again.

  • If the server returns the error: {"error":{"code":"ErrorAccessDenied","message":"Access is denied. Check credentials and try again."}}
  • Verify that the account has the required Microsoft Graph API permissions assigned

6. Import email messages

PaymentService can import existing “eml” files, which are email messages saved in their original format. For these purposes, it is necessary to create an import directory and set its absolute path on the disk in the configuration file under the “emlDir” attribute. PaymentService reads the files in this directory, processes them in the standard way like other e-mail messages downloaded from the mail server, and then deletes the processed files from the import directory.

7. Configuration file

It is necessary to create a configuration XML file for each technology box and place it in the same directory as “PaymentService.exe”. Example configuration file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>

   <add key="rootPath" value="C:\inetpub\wwwroot\netgenium" />

   <add key="stopFrom" value="00:00" />
   <add key="stopTo" value="06:00" />

   <add key="smtpServer" value="localhost" />

   <add key="errorFrom" value="paymentservice@firma.cz" />
   <add key="errorTo" value="support@netgenium.com" />

   <add key="pop3Email" value="ps@firma.cz" />
   <add key="pop3OAuth" value="true" />
   
   <add key="pop3Url" value="pop3.firma.cz" /> 
   <add key="pop3Name" value="ps@firma.cz" />
   <add key="pop3Password" value="pop3heslo" />
   
   <add key="emlDir" value="D:\Services\PaymentService\eml" />

   <add key="infoFrom" value="banka@firma.cz" />
   <add key="infoTo" value="finance@firma.cz" />
   <add key="infoCc" value="" />

  </appSettings>
</configuration>
  • rootPath – the absolute disk path to the NET Genium directory
  • stopFrom – the start time of the technology pause in the format “HH:mm”, during which the PaymentService does not work (it neither downloads nor processes e-mail messages)
  • stopTo – the end time of the technology pause in the format “HH:mm”, during which the PaymentService does not work
  • smtpServer – the address of the outgoing mail server
  • errorFrom – e-mail address from which notifications about possible errors in the PaymentService are sent
  • errorTo – e-mail address to which notifications about possible errors in the PaymentService are sent
  • pop3Email – email address of the technical mailbox
  • pop3OAuth – flag indicating whether enhanced OAuth2 security should be used for authentication together with the configuration file “MicrosoftOAuth.json”
  • pop3Url – the address of the mail server of the incoming mail, optionally with a port number in the form “server name:port number” (the default port is 110); a secure SSL connection is used only on port 995 (for example “pop3.firma.cz:995”), on any other port the service connects without SSL
  • pop3Name – login name to the technology mailbox
  • pop3Password – the password to the technology mailbox
  • emlDir – the absolute path on the disk to the directory from which the PaymentService reads and processes the “eml” files
  • infoFrom – e-mail address from which the notification about the payment will be sent
  • infoTo – e-mail address to which a notification about the payment will be sent
  • infoCc – an optional e-mail address (copy) to which a notification about the payment will be sent

All e-mail messages that arrive in the technology mailbox are deleted after processing.

8. Installation of the service

  • PaymentService is a service that runs in the background of the Windows operating system and automatically activates and downloads emails every 10 minutes. Therefore, it is not enough to simply run the “PaymentService.exe” program, but it is necessary to install the service using the “PaymentService - user.lnk” shortcut. The “PaymentService - user.lnk” shortcut is created automatically by running the “PaymentService.exe” program.
  • The “PaymentService - user.lnk” shortcut opens the service installation dialog. In it, Startup mode needs to be set to “Automatic” and Account to “LocalSystem”; the installation of the service is completed with the “Install” button.
  • The name under which the service is installed and displayed in the Windows operating system service list can be changed using the optional “ServiceName” parameter in the main service configuration file “PaymentService.exe.config”. If the parameter is not specified, the default name “PaymentService” is used. Setting a unique name is useful especially when several independent installations of the service run on a single server and need to be distinguished from each other in the service list.

Obrázek.png

  • You can also uninstall the program by running the “PaymentService.exe” program and clicking the “Uninstall” button.

9. Backing up downloaded email messages

Copies of all e-mail messages delivered to the technology mailbox are automatically saved in the “POP3Downloads\yyyy-MM-dd” subdirectory, which is located in the same directory as “PaymentService.exe”. E-mail messages are stored under a random name (GUID.eml) and are placed in a subdirectory whose name identifies the day the e-mail message was downloaded.

  • Example:
D:\Services\PaymentService\POP3Downloads\2013-05-28\154c463d-386a-4b61-bf0d-6b2cd91a1bcb.eml

Backup subdirectories older than 6 months are deleted by the service itself, as are log files older than one year.

In one run, PaymentService processes at most 500 e-mail messages from the technology mailbox; the rest is processed in the next run. Each e-mail message is written in a separate transaction and the information e-mail about the payment (see chapter 10) is sent only after it is written. Processing that ends with an error thus leaves nothing in the database; the service ends the run and processes the message and all the following ones in the next runs. A message that could not even be downloaded from the technology mailbox is skipped and the service continues with the next one; it tries to download it again in the next run. If the processing fails for the third time, a copy of the message is saved to the “Failed” subdirectory in the same directory as “PaymentService.exe”, the message is deleted from the technology mailbox (a file from the “emlDir” directory is deleted) and an error is written to the log file.

10. Sending notification messages

After a payment is matched with an issued invoice or an issued advance invoice, an information e-mail with the subject “Info o platbě” is sent from the address specified in the “infoFrom” key to the address specified in the “infoTo” key, with a copy to the address in the “infoCc” key. If the “infoFrom” or “infoTo” key is not filled in, no information e-mail is sent. For a partial payment, the text of the e-mail also contains the amount remaining to be paid. If the “infoTo” key contains the address of an SMS e-mail gateway (ending with “@sms.eurotel.cz”, “@sms.cz.o2.com” or “@vodafonemail.cz”), a shortened message is sent. Example of notification email text:

Outgoing invoice No. 130100024 issued to the company Smetáček a lopatka, spol. s.r.o. in the amount of CZK 10,890.00 was paid.

11. Notice

The PaymentService is dependent on the e-mail messages and their content sent by the respective bank. If, for example, the bank does not send an e-mail when paying less than CZK 100, the PaymentService will not capture this movement. In the same way, the service is not able to capture, for example, payments mediated by direct debit or standing order. Therefore, it is not recommended to use PaymentService as the only and full-fledged tool for assigning payments to individual documents. The possibility of importing a monthly account statement into NET Genium and subsequently automatically matching payments based on it is widely used, for example. This functionality can be used concurrently without restrictions with the PaymentService service.