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 is installed and configured
• You have an SFTP account for MPS

Set up an SFTP account for MPS

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

FinDock has created a form to handle the signup process with the required options pre-filled. Please download the PDF, fill in the customer information fields, add the date, sign, and then send the form to FinDock Support.

Install Nordics extension

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

Check and assign the required permissions. If you are using custom permission set groups, ensure the Nordic permission sets are assigned.

Configure KID format

If you haven't done so already, configure the FinDock for Norway extension settings to define your KID format. See below for more information.

Add 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 add an AvtaleGiro target:

AvtaleGiro target settings

• Use New MPS Endpoints: Enable this toggle when MPS notifies you that your account is migrated to their new service IP addresses. This is enabled by default for targets created after the new endpoint rollout.
• Associate charges to: For CAMT file processing, either select or create a Salesforce account record to store transaction charges, such as for reversals, and enter the Salesforce Id of the account here. Some banks include charges within transactions. These charges are stored automatically and matched against a particular account in Salesforce.
• Bank account number: Add the 11 character account number.
• Company Name: Add the organization's name that is associated with the bank account number.
• Data Sender ID: Enter the ID from your AvtaleGiro service contract (from the bank or MPS).
• Duplicate OCR protection: Enable duplicate protection unless you are testing and want to ignore duplicates.
• Enable file transfers with Mastercard Payment Services: When you are done testing, enable this setting for automatic file transfer with the MPS production environment.
• isTest: Enable if you want to use the MPS test environment.
• Number of generated files: This is a running count of the generated payment claims sent to MPS. Leave the default unless there is a specific need to start from another number.
• SFTP user account for Mastercard Payment Services: Enter the production username you got from FinDock as part of the SFTP account signup process.
• Supported Bank Statement format: Select which bank statement type will be used with this account, either camt.053 or camt.054.
• Upload Copy to Chatter: Enable if you want FinDock to upload to Chatter copies of files sent to MPS.

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 a bank Id.
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.

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

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.

Adjust mandate settings for AvtaleGiro

Adjust the Core mandate settings as described below according to your specific AvtaleGiro use case.

• Mandate Reference: Not applicable. This prefix is appended to mandate reference for other direct debit methods. The mandate references for AvtaleGiro are auto-generated to comply with AvtaleGiro rules.
• Reuse existing mandate: You can enable this setting to reuse an existing mandate for a given payer. If 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 reuse is enabled, when the payer sets up a new agreement, FinDock finds and reuses the existing agreement KID, updating the mandate with the new payment details.
• Auto-create mandates: Enable (check) if you want FinDock to automatically create AvtaleGiro agreements (mandates) for new installments and recurring payments.

In the mandate 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.

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
• Collection 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.

However, there is an additional requirement to allow time for the notification handling by the bank. As explained by MPS:

For payment claims with a due date from the 15th of any month (“month x”) to the 14th of the following month, data must be received by Mastercard Payment Services by 14:00 on the last working day of the previous month (the month before “month x”). This ensures that the bank can notify the payer of the upcoming payment within their account statement.

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
• Collection Date: February 14, 2023
• 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.

Norwegian banks may also provide camt.053 files for reconciliation. These files may be delivered via MPS, depending on your contract with them. If they arrive via MPS, FinDock automatically picks them up for processing. You can also process camt.053 files by manually uploading them to Chatter. For further information, please see processing camt.053 files.

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.

Payment API

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

You can use the following messages with the Payment API to test your Autogiro configuration.

Recurring payment

{
    "SuccessURL": "https://www.example.com/success",
    "FailureURL": "https://www.example.com/error",
    "Payer": {
        "Contact": {
            "SalesforceFields": {
                "FirstName": "Test",
                "LastName": "Payment",
                "Email": "testpayment@findock.com"
                },
            },
        "Account":null,
        },
    "Recurring": {
        "StartDate": "2024-09-27",
        "Frequency": "Monthly",
        "Amount":25,
        "CurrencyISOCode": "NOK"
        },
    "PaymentMethod": {
       "Name": "AvtaleGiro",
       "Processor": "FinDock-for-Norway",
       "Target" : "Default-AvtaleGiro-account",
       "Parameters" : {
            "amountLimitFactor" : "10",
            "notification": "true",
            "description": "test payment"
            },
        },
    "Settings": {
        "SourceConnector": "PaymentHub"
        },
}

One-time payment

{
    "SuccessURL": "https://www.example.com/success",
    "FailureURL": "https://www.example.com/error",
    "Payer": {
        "Contact": {
            "SalesforceFields": {
               "FirstName": "Test",
               "LastName": "Payment",
               "Email": "testpayment@findock.com"
                },
            },
        "Account":null,
        },
    "OneTime": {
        "Amount": 25,
        "CurrencyISOCode": "NOK"
        },
   "PaymentMethod": {
       "Name": "AvtaleGiro",
       "Processor": "FinDock-for-Norway",
       "Target" : "Default-AvtaleGiro-account",
       "Parameters" : {
            "amountLimitFactor" : "10",
            "notification": "false",
            "description": "test payment"
            },
        },
   "Settings": {
        "SourceConnector": "PaymentHub"
        }
}