AvtaleGiro direct debit

AvtaleGiro is a direct debit payment method used throughout Norway. The schema is managed and operated by Mastercard Payment Services (MPS), formerly known as NETS. MPS also manages the Norwegian eFaktura invoicing solution. To learn how FinDock supports eFaktura, see our FAQ.

The AvtaleGiro payment method is part of the Nordic Payments for FinDock package. FinDock customers need to sign up with their own Norwegian bank to use FinDock with the AvtaleGiro banking environment.

Pre-requisites

• FinDock installed and configured
• FinDock for Norway installed and configured
• Working connection to ProcessingHub

Set up an SFTP account for MPS

To use the native integration with Mastercard Payment Services (MPS), you need an SFTP account with MPS.

FinDock has created a simple form to handle the signup process. Please reach out to FinDock Support for assistance or if you have any questions.

Install and activate AvtaleGiro

Follow the standard procedure for installing the Nordic Payments payment extension. Activate the FinDock-for-Norway processor and the AvtaleGiro payment method.

Check and assign the required permissions for FinDock features. Assign the FinDock Norway Integration permission set to the integration user profile.

Create AvtaleGiro target(s)

AvtaleGiro payments are created for and reconciled against a specific bank account that is identified by the target. Targets for AvtaleGiro are configured in the Nordic Payments extension settings.

To create an AvtaleGiro target:

1. Launch the FinDock app and go to the Setup tab.
2. Scroll down and click on the Nordic Payments extension tile.
3. Add a new target.
4. Select type Norwegian-Payments and subtype OCR Norway.
5. Add the 11 character account number.
6. Add a name for the account.
7. Enter the Data Sender ID to be able to connect to the MPS file service.
8. Enable duplicate OCR protection (unless you want it off for testing.
9. Enable isTest if you want to use the MPS test environment.
10. Click Save.

Mandate management with AvtaleGiro

AvtaleGiro requires an active Agreement to be created and registered before the direct debit payment can be collected. The Agreement is represented by a Mandate record in FinDock.

Payers can set up new mandates through FinDock. Creating and changing agreements is managed by the payers at their bank. A merchant cannot cancel or modify active mandates, but receives updates when there are changes (canceled, new or updated) to agreements at the payer’s bank.

The following illustration shows the basic online setup flow for new agreements.

1. Payer initiates a one-time or recurring payment thru FinDock Giving Pages, PayLinks or custom payment form.
2. FinDock creates a new mandate with status Pending Registration.
3. Payer is redirected to MPS authorization form where payer enters bankID.
4. The new agreement is submitted to MPS.
5. MPS sets up the agreement with the payer’s bank.
6. FinDock gets agreement registration confirmation via OCR giro file from MPS, activates the mandate and changes its status to Success.

Customer identifier (KID)

An AvtaleGiro mandate is identified by a unique customer identifier called the KID (kundeidentifikasjon). FinDock generates and manages the KID for AvtaleGiro payments. The format of the KID is defined as part of the merchant’s agreement with their bank.

A KID is different from how FinDock normally works with mandate references. It not only identifies mandates, but it also serves as a unique reference for each direct debit payment.

The KID can have up to 25 characters, and it has an internal 4-part structure. FinDock supports one kid format in the order specified below.

1. Customer Number (required): identifies the payer and the active mandate
2. Payment Type (optional): if a merchant prefers to have more than one agreement per payer, they can use payment type to differentiate agreements.
3. Invoice ID (required): identifies individual payments taken from the payer; also needed for setting up a new mandate, but has no functional impact.
4. Control Digit (required): either Modulo 10 or 11 to make sure that the full KID value is valid and has not been subjected to tampering.

caution

Using custom or recurring payment references is highly discouraged, since FinDock automatically generates valid payment references based on the mandate.

FinDock stores these KID components in different locations and generates the KID as part of the record creation flow.

KID component	Object	Field	Example
Customer Number	Account or Contact	Customer ID (npff__Customer_ID__c)	12345678
Payment Type	Mandate	Payment Type (npff__Payment_Type__c)	01
Customer Reference	Mandate	Custom Reference (cpm__Custom_Reference__c)	12345678
Control Digit	N/A	N/A (generated based on KID configuration)
Full KID	Installment	Final Payment Reference (cpm__Final_Payment_Reference__c)	1234567800001
Full KID	Mandate	KID (npff_KID_c)	1234567812341

Configuring the KID format

Before you can set up new AvtaleGiro agreements and collect payments, you need to define the KID format FinDock must use in accordance with the contract with your bank.

The KID format configuration is part of the FinDock for Norway setup.

Reuse and automatically create AvtaleGiro mandates

FinDock Core includes settings that impact direct debit mandates. These are under the main setup page behind the Mandates tile.

If you would like to reuse existing AvtaleGiro agreements, click the tile and enable the reuse mandate setting. The reference setting does not impact AvtaleGiro payment processing.

If mandate reuse is not enabled, FinDock creates a new mandate with new Customer Id and KID when an existing payer (contact or account) sets up a new payment agreement.

If mandate reuse is enabled, when the payer sets up a new payment agreement, FinDock finds and reuses the existing agreement KID, updating the mandate with the new payment details.

In the reuse scenario, there are limitations to keep in mind:

• Payment Type must be disabled.
• The Beløpgrense factor must be high enough to accommodate the new payment(s) on the existing agreement.

In addition to reuse, you can automatically create mandates, for example, when a customer service agent manually adds a new opportunity to Salesforce.

If you would like to automatically create AvtaleGiro agreements (mandates) for new opportunities and recurring payments/donations, enable the Autocreate mandate for Direct Debits setting in the Core mandates configuration.

Creating new agreements with FinDock

New agreements are set up via the FinDock Payment API. This can be done with FinDock Giving Pages, PayLinks, or with custom API integration.

FinDock redirects payers to the AvtaleGiro banking environment where they can complete the agreement setup with MPS. For each new agreement, FinDock immediately creates:

• A Mandate record
• A Payment Profile record
• An Installment record for new one-time payment
• A Recurring Payment record for recurring payments (or source-specific object recording such as Gift Commitment for Salesforce Fundraising and NPC)

The Mandate record representing the agreement goes through three states:

1. When the new agreement is started, FinDock creates a mandate with the status Pending Registration.
2. After the payer completes the agreement setup process with MPS, FinDock updates the mandate status to Pending Registration Acceptance.
3. When FinDock receives agreement success confirmation from MPS, the mandate status is set to Success and Active is set to true.

The mandate also stores the payer’s notification preference with the fields Notification Channel and Notification Preference. The channel is either merchant (Own), which is the default, or bank (Bank). The preference is either true or false depending on the payer’s selection when creating the new payment.

Collecting AvtaleGiro payments

Once you have a registered agreement (mandate is active with Success status), you can collect payments. This is handled through payment schedules.

Based on the schedule parameters, FinDock creates an OCR giro payment claim file. The generated file is automatically uploaded to the MPS processing service.

AvtaleGiro timelines

When collecting AvtaleGiro payments, it is important to keep in mind the required timelines for submitting payment claims. There are two specific factors you need that impact your collection time (due date):

• Does the payer require notification of an upcoming payment?
• Is the notification sent by the bank or by the merchant (Bank or Own)?

If no notification is required, you can submit your payment claim any time before the due date.

If notification is required, the submission date depends on the notification type. Both types of notification can be in one OCR giro file.

Merchant notification

If your organization is sending payment notifications, the payment claim needs to be submitted to MPS four (4) business days before the due date (until 14:00 on the fourth day).

Example

• Due date: Friday, January 20, 2023
• Submission deadline: Monday, January 16, 2023, by 14:00
• Notification deadline: Tuesday, January 17, 2023

To collect payments with a due date on or before January 20th, your payment schedule setup should be as follows:

• Run Date: January 16, 2023
• Selection Date: January 20, 2023
• Due Date: January 20, 2023
• Additional SOQL:
  AND (Mandate__r.Notification_Channel__c = ‘BANK’ AND Mandate__r.Notification_Preference__c = ‘NO’) OR (Mandate__r.Notification_Channel__c = ‘OWN’ AND Mandate__r.Notification_Preference__c = ‘Yes')

Bank notification

If your bank is sending payment notifications, the payment claim needs to be submitted to MPS ten (10) business days (two calendar weeks) before the due date.

Example

• Due date: January 15th thru February 14th, 2023
• Submission deadline: Last working day of December

To collect payments with a due date on or before January 15th, your payment schedule setup should be as follows:

• Run Date: December 30, 2023
• Selection Date: February 14, 2023
• Due Date: Any date between 15th of January & 14th of February
• Additional SOQL:
  AND Mandate__r.Notification_Channel__c = ‘BANK’ & Mandate__r.Notification_Preference__c = ‘Yes’

Reconciliation with AvtaleGiro

FinDock performs reconciliation of AvtaleGiro payments and changes to mandates through sending and receiving OCR files. The reconciliation with MPS (and the payer’s bank) starts with the initial OCR payment claim file upload from FinDock.

Payment claim report

The payment claim OCR file is sent to MPS as part of the payment schedule process. The MPS service runs initial checks to confirm the file and its contents. The claim report is sent back to FinDock as a CSV file which FinDock handles as follows:

• If there are errors on file level, all installments included in the claim are set to Rejected.
• If there are errors on transaction (“order”) level, FinDock parses them into inbound reports and updates the impacted installments.

For further details on error codes and resulting actions, please see Processing OCR files.

Incoming OCR giro files

FinDock automatically polls the MPS file transfer service for new OCR files. For further details of the overall reconciliation flow, please see Processing OCR files.

Mandates are identified by the Customer Reference part of their KID which is stored in FinDock as the Mandate Id.

1. FinDock receives a file with new, updated and or canceled mandates (agreements).
2. ProcessingHub extracts the file and pushes the mandates to Salesforce as Inbound Report records.
3. Matching in Salesforce looks for existing mandates with the same Mandate Id.
4. If a match is found, the mandate is activated and the status is set to Success.
5. If no match is found, the inbound report can be further processed through Guided Matching and/or reviewed manually.

OCR file lines for AvtaleGiro payments are parsed into Transaction Set records and related Transaction records. FinDock creates new installments and updates existing installments according to the extracted information.

Initial matching to existing installments is based on predefined Guided Matching rules, which you can expand according to your needs. FinDock will try to match an installment based on the payment reference and end-to-end Id values.

AvtaleGiro payment API parameters

The AvtaleGiro payment method includes optional parameters that can be set in the API call (and in the payments details configuration for Giving Pages or PayLinks).

• Amount Limit Factor: multiple of chosen amount (influences the Beløpgrense)
• Notification: True (opt-in) or False (opt-out) for receiving a notifications of upcoming payments