Configuring Vipps for FinDock

The Vipps mobile payment application is used throughout Norway. FinDock integrates with the Vipps service to initiate and collect payments.

info

When you sign up as a new Vipps merchant, please make sure you select FinDock as your partner in the signup process for "Vipps på nett."

Multi-merchant	Multi-currency

Payment Method	One-time	Recurring	Refunds
Vipps

Pre-requisites

• FinDock installed and configured
• Successful WebHub connection
• A Vipps merchant account

Install and activate Vipps extension

Follow the standard procedure for installing and activating the Vipps for FinDock payment extension. Activate the payment method Vipps.

Check and assign the required permissions for FinDock features and the Vipps payment extension.

Configure Vipps extension

To up the Vipps extension is fairly straightforward. You just need to copy some details from your Vipps portal to the FinDock extension setup. We recommend having both the Vipps portal and FinDock open in different browser tabs so you can copy directly from one to the other.

Before you begin, determine if you are setting up a production or test environment. If you are testing, select the Test option in the portal before copying any information.

To configure Vipps for FinDock:

1. Launch the FinDock app and go to the Setup tab.
2. Scroll down and click on the Vipps payments extension tile.
3. For the merchant account you want to integrate, add the following details:
   • Name: name for your Vipps account; ensure names are easily distinguishable
   • Merchant Serial Number: MSN from Vipps portal for the given account
   • Client Key: API client key from Vipps portal
   • Client Secret: API client secret from Vipps portal
   • Subscription Key: API Subscription key from Vipps Portal (either primary or secondary)
   • IsTest: Enable if you are setting up a test environment
   • Product Name: Default name of Recurring Agreements setup in Vipps, can be overwritten via the API
   • Merchant Agreement Url: Default URL for setting up recurring agreements. Visible to end users in their App. Can be overwritten via the API
   • RetryDays: How many days Vipps should retry a failed recurring payment. Recommended to be at least 3, to ensure success.
4. Click Save.
5. If you are integrating multiple accounts, click Add Account and repeat the steps above for each account.

Reconciling Vipps Payments

Vipps payments can originate from different sources. Next to one-time & recurring online payments, it is also possible to transfer money directly to a merchant via a Vipps number. FinDock reconciles payments using a daily, automated import of transactions from Vipps. These transactions contain refunds, confirmed payments and payouts from Vipps. The reconciliation only happens when:

1. Enable Reconciliation Incoming Payments is enabled
2. Initial ledger date is filled.
3. There are new payments that need to be retrieved from Vipps.

The process to retrieve payments proceeds according to the following steps:

1. Daily heartbeat job checks if there are payments that need to be retrieved from Vipps.
2. If there are new payments, FinDock retrieves all new payments by creating a message record for each retrieval job and an individual message for each transaction.
3. Individual Inbound Reports are created to process the Vipps payments and reconcile them via Guided Matching against installments.

caution

Currently the Vipps Reporting API does not retrieve payments made via Vipps numbers. If you want to process these payments, you can use Guided Matching to reconcile them.

In addition to the settings required for integrating FinDock to Vipps, you need to indicate from which date FinDock should start fetching transaction data from your Vipps ledger. If you have previously used some other integration setup, this date can be considered the official switchover to FinDock handling of Vipps payments.

On the target you can set the initial ledger date that FinDock uses to reconcile transactions. After you have also enabled the toggle to start fetching transactions, FinDock will pull in all available transactions from the initial ledger date.

Vipps data mapping

The table below summarizes the payment data FinDock captures to manage Vipps transactions.

Vipps data	Object	Field	Value
N/A	Payment Profile	Record Type	Wallet
Vipps	Payment Profile	Wallet Type	Vipps
Agreement ID	Mandate	Mandate Id	E.g. agr_123456
Product Name	N/A	Product Name	API parameter ProductName
Bank Statement Description	Installment	Product	API parameter description
Order ID	Installment	Payment Reference	E.g. pi-123456789
Transaction Text	Installment	Bank Statement Description	E.g. Invoice #1234

Vipps mobile phone number handling

With the Vipps payment method, the payer’s mobile phone number plays a central role in the transaction.

When using Vipps through FinDock Giving Pages or Paylinks, you can:

• Use a URL query to pre-fill the payment form with a phone number from Contact or Account. If the payer enters a different number, FinDock uses the value entered by the payer.
• Set the default value of the API Parameter using default values. This enables you to use any phone number field to send to Vipps.

When using Vipps through a custom front-end for the FinDock Payment API:

• Make the phone number API parameter visible for the payer. FinDock uses the value entered by the payer in the Vipps redirect.

note

Vipps can only be used with Norwegian Krone.

Managing a recurring agreement

When setting up a recurring payment in Vipps, the payer will see the agreement in the Vipps app. If a payer wants to cancel their agreement, it is highly recommended to also cancel the agreement in Vipps. FinDock allows you to integrate canceling the Vipps Agreement into your own processes via an Invocable Action. For more information on how an invocable action can be used, see the Salesforce documentation.

The Cancel Vipps Agreement invocable action is an Apex Action with 2 input parameters. You can either supply the Apex action with a Mandate Record ID or the Vipps Agreement ID.

You can use the following combination to cancel a Vipps agreement:

1. In a Flow, for instance, when cancelling recurring payments: Apex Action (recommended): use Cancel Vipps Agreement. This is the recommended way of integrating with a Flow.
2. Use the Global class.

Using Vipps Cancel Agreement in a Flow

To use the invocable in a Flow:

1. In your Flow add an Apex Action.
2. Search for Cancel Vipps Agreement Under Set Input Values, toggle the parameters to “Include”. Note: Please make sure to either toggle Mandate Id OR Agreement Id depending on what input variable you wish to use.
3. Either manually assign your own variables to the output parameters under “Advanced” or use the default [api_name_of_your_action].isvalid and [api_name_of_your_action].message.

Setting	Description	Example values	API name
Is Success	Whether the cancellation performed in Vipps was successful	True or False	[your_apex_action].isSucces
Message	Return message from Vipps if available	Agreement is already cancelled	[your_apex_action].message

When executed, the Apex Action sets two variables that indicate whether the provided combination was valid or not. If the combination is not valid, a message with more information is returned if available. If the cancellation is successful, FinDock will also deactivate the Mandate and set the status to cancelled.

Testing with the Payment API

You can use the following example messages to test if the Vipps configuration is working as expected.

{
    "SuccessURL": "https://www.example.com/success",
    "FailureURL": "https://www.example.com/error",
    "Payer": {
        "Contact": {
            "SalesforceFields": {
                "FirstName": "Eric",
                "LastName": "Johnson",
                "Email": "eric@johnson.com"
            }
        }
    },
    "OneTime": {
        "Amount": "36"
    },
    "PaymentMethod": {
        "Name": "Vipps",
        "Processor": "FinDock-Vipps",
        "Parameters": {
            "mobileNumber": "[Vippstestnumber]"
        }
    }
}